From 0a7fd43daa720b8d45a2b5af7a6c49b70cc3eef7 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 3 Nov 2026 10:30:55 +0000 Subject: [PATCH 01/16] Define strict quality plans and deterministic evidence evaluation --- Cargo.lock | 1068 +++++++++++++++++++++++++++++++++++++++++++++++ Cargo.toml | 45 ++ src/evaluate.rs | 612 +++++++++++++++++++++++++++ src/evidence.rs | 282 +++++++++++++ src/lib.rs | 117 ++++++ src/plan.rs | 349 ++++++++++++++++ 6 files changed, 2473 insertions(+) create mode 100644 Cargo.lock create mode 100644 Cargo.toml create mode 100644 src/evaluate.rs create mode 100644 src/evidence.rs create mode 100644 src/lib.rs create mode 100644 src/plan.rs diff --git a/Cargo.lock b/Cargo.lock new file mode 100644 index 0000000..266e91f --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,1068 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "aho-corasick" +version = "1.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba" +dependencies = [ + "memchr", +] + +[[package]] +name = "anstream" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d" +dependencies = [ + "anstyle", + "anstyle-parse", + "anstyle-query", + "anstyle-wincon", + "colorchoice", + "is_terminal_polyfill", + "utf8parse", +] + +[[package]] +name = "anstyle" +version = "1.0.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000" + +[[package]] +name = "anstyle-parse" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e" +dependencies = [ + "utf8parse", +] + +[[package]] +name = "anstyle-query" +version = "1.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc" +dependencies = [ + "windows-sys", +] + +[[package]] +name = "anstyle-wincon" +version = "3.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d" +dependencies = [ + "anstyle", + "once_cell_polyfill", + "windows-sys", +] + +[[package]] +name = "arrayvec" +version = "0.7.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56" + +[[package]] +name = "bitflags" +version = "2.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06" + +[[package]] +name = "blake3" +version = "1.8.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6d9e454fc11f76977dc803893aff6304ed33d6a26efae8696573bea74baa27ae" +dependencies = [ + "arrayvec", + "cc", + "cfg-if", + "constant_time_eq", + "cpufeatures 0.3.1", +] + +[[package]] +name = "block-buffer" +version = "0.10.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71" +dependencies = [ + "generic-array", +] + +[[package]] +name = "bstr" +version = "1.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6bb31b46c14244e20ee9984b11bf5c992b91fb6939fea616e3512c8baecdbe5f" +dependencies = [ + "memchr", + "serde_core", +] + +[[package]] +name = "cc" +version = "1.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "375989decec1a0fa424442bed520fa12ede43a48475ce8c7417d2c69b32b5f6b" +dependencies = [ + "find-msvc-tools", + "shlex", +] + +[[package]] +name = "cfg-if" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600" + +[[package]] +name = "cfg_aliases" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527" + +[[package]] +name = "clap" +version = "4.6.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aa8876b300ab35ba921adea3dfd70157a46249b33f95c9084ae5709785478946" +dependencies = [ + "clap_builder", + "clap_derive", +] + +[[package]] +name = "clap_builder" +version = "4.6.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec0797fb7aeb1406c84efac526901f7ec3ead2124f946b494e72879d4b54704d" +dependencies = [ + "anstream", + "anstyle", + "clap_lex", + "strsim", +] + +[[package]] +name = "clap_derive" +version = "4.6.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f9c751b79415d4e559e3d1fcf128e09e720eb673a06d26cf6f392d37d75b66e0" +dependencies = [ + "heck", + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "clap_lex" +version = "1.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1c133bc6a41be0d194c306b5506d15e6feeea7b1d6604bd3f8310dfb2ca96486" + +[[package]] +name = "colorchoice" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570" + +[[package]] +name = "constant_time_eq" +version = "0.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3d52eff69cd5e647efe296129160853a42795992097e8af39800e1060caeea9b" + +[[package]] +name = "cpufeatures" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280" +dependencies = [ + "libc", +] + +[[package]] +name = "cpufeatures" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5ca28b0ae3115b884660db4118d803791fd6756b6e88f39c0f3f7859060d7566" +dependencies = [ + "libc", +] + +[[package]] +name = "crossbeam-deque" +version = "0.8.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "622f3fc73690be383c7214310406f28a90e6edeadc3cea882f9d71e495b9711a" +dependencies = [ + "crossbeam-epoch", + "crossbeam-utils", +] + +[[package]] +name = "crossbeam-epoch" +version = "0.9.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc74980687109a3b14c72fd458107bf0baa1da1a1a805e178d15501ba9b86d9d" +dependencies = [ + "crossbeam-utils", +] + +[[package]] +name = "crossbeam-utils" +version = "0.8.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6" + +[[package]] +name = "crypto-common" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a" +dependencies = [ + "generic-array", + "typenum", +] + +[[package]] +name = "digest" +version = "0.10.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292" +dependencies = [ + "block-buffer", + "crypto-common", +] + +[[package]] +name = "displaydoc" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "equivalent" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826" + +[[package]] +name = "errno" +version = "0.3.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb" +dependencies = [ + "libc", + "windows-sys", +] + +[[package]] +name = "fastrand" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223" + +[[package]] +name = "find-msvc-tools" +version = "0.1.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1c66915cc5391097de7a2b0b972e8505aa33c0df401fd3a6811dbdb32881ba48" + +[[package]] +name = "form_urlencoded" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf" +dependencies = [ + "percent-encoding", +] + +[[package]] +name = "generic-array" +version = "0.14.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a" +dependencies = [ + "typenum", + "version_check", +] + +[[package]] +name = "getrandom" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099" +dependencies = [ + "cfg-if", + "libc", + "r-efi", +] + +[[package]] +name = "globset" +version = "0.4.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e47d37d2ae4464254884b60ab7071be2b876a9c35b696bd018ddcc76847309cd" +dependencies = [ + "aho-corasick", + "bstr", + "log", + "regex-automata", + "regex-syntax", +] + +[[package]] +name = "hashbrown" +version = "0.17.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" + +[[package]] +name = "heck" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" + +[[package]] +name = "icu_collections" +version = "2.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4c6b649701667bbe825c3b7e6388cb521c23d88644678e83c0c4d0a621a34b43" +dependencies = [ + "displaydoc", + "potential_utf", + "yoke", + "zerofrom", + "zerovec", +] + +[[package]] +name = "icu_locale_core" +version = "2.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "edba7861004dd3714265b4db54a3c390e880ab658fec5f7db895fae2046b5bb6" +dependencies = [ + "displaydoc", + "litemap", + "tinystr", + "writeable", + "zerovec", +] + +[[package]] +name = "icu_normalizer" +version = "2.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5f6c8828b67bf8908d82127b2054ea1b4427ff0230ee9141c54251934ab1b599" +dependencies = [ + "icu_collections", + "icu_normalizer_data", + "icu_properties", + "icu_provider", + "smallvec", + "zerovec", +] + +[[package]] +name = "icu_normalizer_data" +version = "2.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7aedcccd01fc5fe81e6b489c15b247b8b0690feb23304303a9e560f37efc560a" + +[[package]] +name = "icu_properties" +version = "2.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "020bfc02fe870ec3a66d93e677ccca0562506e5872c650f893269e08615d74ec" +dependencies = [ + "icu_collections", + "icu_locale_core", + "icu_properties_data", + "icu_provider", + "zerotrie", + "zerovec", +] + +[[package]] +name = "icu_properties_data" +version = "2.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "616c294cf8d725c6afcd8f55abc17c56464ef6211f9ed59cccffe534129c77af" + +[[package]] +name = "icu_provider" +version = "2.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85962cf0ce02e1e0a629cc34e7ca3e373ce20dda4c4d7294bbd0bf1fdb59e614" +dependencies = [ + "displaydoc", + "icu_locale_core", + "writeable", + "yoke", + "zerofrom", + "zerotrie", + "zerovec", +] + +[[package]] +name = "idna" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de" +dependencies = [ + "idna_adapter", + "smallvec", + "utf8_iter", +] + +[[package]] +name = "idna_adapter" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3acae9609540aa318d1bc588455225fb2085b9ed0c4f6bd0d9d5bcd86f1a0344" +dependencies = [ + "icu_normalizer", + "icu_properties", +] + +[[package]] +name = "ignore" +version = "0.4.30" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7b009b6744c1445efd7244084e25e498636412effb6760b55067553baa925cc7" +dependencies = [ + "crossbeam-deque", + "globset", + "log", + "memchr", + "regex-automata", + "same-file", + "walkdir", + "winapi-util", +] + +[[package]] +name = "indexmap" +version = "2.14.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855" +dependencies = [ + "equivalent", + "hashbrown", +] + +[[package]] +name = "is_terminal_polyfill" +version = "1.70.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695" + +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + +[[package]] +name = "libc" +version = "0.2.191" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a" + +[[package]] +name = "linux-raw-sys" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53" + +[[package]] +name = "litemap" +version = "0.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae" + +[[package]] +name = "log" +version = "0.4.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d15f86d12da44cd8d4ec3c73984537eb7f4cadcb9776a575a0a8a05ca11005c" + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "nix" +version = "0.31.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d" +dependencies = [ + "bitflags", + "cfg-if", + "cfg_aliases", + "libc", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + +[[package]] +name = "once_cell_polyfill" +version = "1.70.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe" + +[[package]] +name = "percent-encoding" +version = "2.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220" + +[[package]] +name = "potential_utf" +version = "0.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d83eb9bc6d8e5cf568e7a1101d60ee05e81ed50ea106026f3d18deeb046d7661" +dependencies = [ + "zerovec", +] + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "r-efi" +version = "6.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf" + +[[package]] +name = "regex-automata" +version = "0.4.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2" +dependencies = [ + "aho-corasick", + "memchr", + "regex-syntax", +] + +[[package]] +name = "regex-syntax" +version = "0.8.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4" + +[[package]] +name = "rustix" +version = "1.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5e76742e5294153d4dde1207dbec5bdd81eef6fabdc0d2118babadabfd858aa" +dependencies = [ + "bitflags", + "errno", + "libc", + "linux-raw-sys", + "windows-sys", +] + +[[package]] +name = "same-file" +version = "1.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502" +dependencies = [ + "winapi-util", +] + +[[package]] +name = "sealmap-corpus" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d0281344b60c27a86abbea1289ffd8d2f6538ea7bf9c1de4ce9e0a8c14b39126" +dependencies = [ + "blake3", + "sealmap-dense", + "sealmap-mermaid", + "sealmap-model", + "serde", + "serde_json", + "thiserror", + "toml", +] + +[[package]] +name = "sealmap-dense" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1b8eebf512c3fcbab8c66c46971cf68480892ee4d4a3dc11d49418dbefbf41aa" +dependencies = [ + "sealmap-model", +] + +[[package]] +name = "sealmap-mermaid" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "05844d2c39aad7da7544c7fd774dcad4fbd5f214fbc02cbf40991f1c0e7bde36" +dependencies = [ + "sealmap-model", +] + +[[package]] +name = "sealmap-model" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9454c279810b116510934e278523dc985b296531b7dcd0fc6bcc26f90534c012" +dependencies = [ + "blake3", + "ignore", + "serde", + "serde_json", + "thiserror", +] + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_json" +version = "1.0.154" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "serde_spanned" +version = "0.6.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3" +dependencies = [ + "serde", +] + +[[package]] +name = "sha2" +version = "0.10.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283" +dependencies = [ + "cfg-if", + "cpufeatures 0.2.17", + "digest", +] + +[[package]] +name = "shlex" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" + +[[package]] +name = "signal-hook" +version = "0.3.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d881a16cf4426aa584979d30bd82cb33429027e42122b169753d6ef1085ed6e2" +dependencies = [ + "libc", + "signal-hook-registry", +] + +[[package]] +name = "signal-hook-registry" +version = "1.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b" +dependencies = [ + "errno", + "libc", +] + +[[package]] +name = "smallvec" +version = "1.16.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d0d5d4b1981b8bbbb7aed204cae5726d683d5d6ac7e74ec54122ea28f315e7c8" + +[[package]] +name = "stable_deref_trait" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596" + +[[package]] +name = "strsim" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" + +[[package]] +name = "syn" +version = "3.0.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "synstructure" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "tempfile" +version = "3.27.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd" +dependencies = [ + "fastrand", + "getrandom", + "once_cell", + "rustix", + "windows-sys", +] + +[[package]] +name = "thiserror" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e" +dependencies = [ + "thiserror-impl", +] + +[[package]] +name = "thiserror-impl" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "tinystr" +version = "0.8.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "abc840c238154d58f9e86b2792261edfde565a17696e1cda1a449de27979801a" +dependencies = [ + "displaydoc", + "zerovec", +] + +[[package]] +name = "toml" +version = "0.8.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362" +dependencies = [ + "serde", + "serde_spanned", + "toml_datetime", + "toml_edit", +] + +[[package]] +name = "toml_datetime" +version = "0.6.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c" +dependencies = [ + "serde", +] + +[[package]] +name = "toml_edit" +version = "0.22.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a" +dependencies = [ + "indexmap", + "serde", + "serde_spanned", + "toml_datetime", + "toml_write", + "winnow", +] + +[[package]] +name = "toml_write" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801" + +[[package]] +name = "typenum" +version = "1.20.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20" + +[[package]] +name = "unicode-ident" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" + +[[package]] +name = "url" +version = "2.5.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed" +dependencies = [ + "form_urlencoded", + "idna", + "percent-encoding", + "serde", +] + +[[package]] +name = "utf8_iter" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "af3bd9d3e571c26fcce9d033b87ea5ab061b8d2ffe9b7a5675d810d68f03edf0" +dependencies = [ + "utf_types", +] + +[[package]] +name = "utf8parse" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821" + +[[package]] +name = "utf_types" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3a3b425286980a367278453f3b6d28cdcb134b574e5a35824a6ff5eebad50bb6" + +[[package]] +name = "version_check" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" + +[[package]] +name = "visioncraft" +version = "0.1.0" +dependencies = [ + "clap", + "nix", + "sealmap-corpus", + "serde", + "serde_json", + "sha2", + "signal-hook", + "tempfile", + "thiserror", + "url", +] + +[[package]] +name = "walkdir" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b" +dependencies = [ + "same-file", + "winapi-util", +] + +[[package]] +name = "winapi-util" +version = "0.1.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22" +dependencies = [ + "windows-sys", +] + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-sys" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" +dependencies = [ + "windows-link", +] + +[[package]] +name = "winnow" +version = "0.7.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945" +dependencies = [ + "memchr", +] + +[[package]] +name = "writeable" +version = "0.6.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc" + +[[package]] +name = "yoke" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "417ef3fcf6c300b7dbd25c85531a746931c02ad536f3cf4786ed1e88223340b3" +dependencies = [ + "stable_deref_trait", + "yoke-derive", + "zerofrom", +] + +[[package]] +name = "yoke-derive" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec8ebde2db3681e8c9980cc27822030e68752690ddfa9473e739aeb4dbde6d71" +dependencies = [ + "proc-macro2", + "quote", + "syn", + "synstructure", +] + +[[package]] +name = "zerofrom" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272" +dependencies = [ + "zerofrom-derive", +] + +[[package]] +name = "zerofrom-derive" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a" +dependencies = [ + "proc-macro2", + "quote", + "syn", + "synstructure", +] + +[[package]] +name = "zerotrie" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ea269c3bd32f0a32c321907a2ae912ba6f4649bb0fc764a15627e99a7095a3f" +dependencies = [ + "displaydoc", + "yoke", + "zerofrom", +] + +[[package]] +name = "zerovec" +version = "0.11.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f58a2799cfe9a1670c7ea8edbd52ef8edb93cb37a7f83bf31ba9e35d9dae6a40" +dependencies = [ + "yoke", + "zerofrom", + "zerovec-derive", +] + +[[package]] +name = "zerovec-derive" +version = "0.11.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3743ddbf47738d929cd1ae2e199d40d0162979dfe31aef8ae646d2bf00bf97a" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..bcf5c3f --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,45 @@ +[package] +name = "visioncraft" +version = "0.1.0" +edition = "2024" +rust-version = "1.85" +description = "Explicit quality plans, bounded execution receipts and deterministic evidence gates" +license = "MIT OR Apache-2.0" +repository = "https://github.com/DreamLab-AI/visioncraft" +readme = "README.md" +keywords = ["quality", "evidence", "testing", "development"] +categories = ["development-tools::testing"] + +[features] +default = ["cli", "process"] +cli = ["process", "dep:clap", "dep:url"] +process = ["dep:tempfile", "dep:nix", "dep:signal-hook"] + +[[bin]] +name = "visioncraft" +path = "src/main.rs" +required-features = ["cli"] + +[dependencies] +serde = { version = "1", features = ["derive"] } +serde_json = "1" +thiserror = "2" +sha2 = "0.10" +sealmap-corpus = "0.4.0" +clap = { version = "4", features = ["derive"], optional = true } +tempfile = { version = "3.27", optional = true } +url = { version = "2.5", optional = true } + +[target.'cfg(unix)'.dependencies] +nix = { version = "0.31.3", features = ["process", "signal"], optional = true } +signal-hook = { version = "0.3", optional = true } + +[lints.rust] +missing_docs = "warn" +unsafe_code = "forbid" + +[profile.dev] +debug = 0 + +[profile.test] +debug = 0 diff --git a/src/evaluate.rs b/src/evaluate.rs new file mode 100644 index 0000000..9f757b9 --- /dev/null +++ b/src/evaluate.rs @@ -0,0 +1,612 @@ +//! Read-only evaluation of explicit plans, exact receipts and supplied context. + +use crate::plan::same_inputs; +use crate::{ + AuditReceipt, AuditVerdict, ContractError, Evaluator, EvidenceCategory, ExecutionReceipt, + Expectation, FamilyCatalogue, ManualObservation, ProcessStatus, QualityPlan, Subject, + VerifiedArtifacts, artifact_shape, identifier, nonempty, +}; +use serde::{Deserialize, Serialize}; +use std::collections::{BTreeMap, BTreeSet}; + +/// Result of a check under its recorded evaluator policy. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "kebab-case")] +pub enum CheckOutcome { + /// Completed evidence satisfies the declared check policy. + Passed, + /// Completed evidence fails that policy or contradicts an expectation. + Blocked, + /// Explicitly disabled or unavailable; never a required pass. + Skipped, + /// Evidence, scope, freshness or independence is insufficient. + Inconclusive, + /// Invalid evidence or failed execution/capture/evaluator. + Error, +} + +/// Aggregate decision, preserving incomplete evidence separately from defects. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "kebab-case")] +pub enum GateOutcome { + /// Every required check and expectation passed its explicit policy. + Passed, + /// At least one completed required check/expectation blocks. + Blocked, + /// Required evidence is missing, skipped, stale or inconclusive. + Incomplete, + /// Invalid contract or execution/evaluator error prevents a decision. + Error, +} + +/// Recorded outcome and limitations for one planned check. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct CheckReport { + /// Plan-local check identity. + pub id: String, + /// Whether this check is required by the unchanged plan. + pub required: bool, + /// Attempt used, if exactly one was supplied. + pub attempt_id: Option, + /// Scoped policy outcome. + pub outcome: CheckOutcome, + /// Missing evidence, observed failures or explicit interpretation limits. + pub reasons: Vec, +} + +/// Evidence coverage for one expectation, not a semantic proof of its prose. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct ExpectationReport { + /// Expectation identity from the plan. + pub id: String, + /// Whether this expectation is required by the unchanged plan. + pub required: bool, + /// Coverage/assessment outcome. + pub outcome: CheckOutcome, + /// Scope limits and unmet requirements. + pub reasons: Vec, +} + +/// Deterministic evaluation output; no delivery stage is inferred. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct GateReport { + /// Aggregate policy result, not a security certification. + pub outcome: GateOutcome, + /// Unchanged declared required-check denominator. + pub required_checks: usize, + /// Required checks satisfying their policy in this evaluation. + pub passed_required_checks: usize, + /// Every planned check, including missing and optional checks. + pub checks: Vec, + /// Every planned expectation, including unsupported ones. + pub expectations: Vec, + /// Structural errors in the supplied data, without raw document contents. + pub errors: Vec, +} + +impl GateReport { + /// Whether the declared gate policy passed with complete required evidence. + pub fn passed(&self) -> bool { + self.outcome == GateOutcome::Passed + } +} + +/// External facts supplied explicitly; the library performs no IO or clock reads. +#[derive(Debug)] +pub struct EvaluationContext<'a> { + /// Evaluation time in milliseconds since the Unix epoch. + pub now_ms: u64, + /// Current source/configuration snapshot, independently obtained by caller. + pub current_subject: &'a Subject, + /// Exact captured evidence bytes verified by the caller in memory. + pub verified: &'a VerifiedArtifacts, + /// Revisions known to be ancestors of the current revision. Empty means + /// unknown ancestry when the current and recorded revisions differ. + pub ancestor_revisions: &'a [String], + /// Optional exact aliases for served model families, governed by the caller. + pub families: FamilyCatalogue, + /// Post-run audit records; absent required audits remain incomplete. + pub audits: &'a [AuditReceipt], + /// Post-run manual observations; their meaning is assessed by the observer. + pub manual_observations: &'a [ManualObservation], +} + +impl<'a> EvaluationContext<'a> { + /// Construct a context with no inferred ancestry, audits or family aliases. + pub fn new(now_ms: u64, current_subject: &'a Subject, verified: &'a VerifiedArtifacts) -> Self { + Self { + now_ms, + current_subject, + verified, + ancestor_revisions: &[], + families: FamilyCatalogue::default(), + audits: &[], + manual_observations: &[], + } + } +} + +fn context_limits(plan: &QualityPlan, context: &EvaluationContext<'_>) -> Vec { + let mut reasons = Vec::new(); + let recorded = &plan.subject; + let current = context.current_subject; + if recorded.repository != current.repository || recorded.configuration != current.configuration + { + reasons.push("current repository/configuration differs from reviewed subject".into()); + } + if !same_inputs(&recorded.inputs, ¤t.inputs) { + reasons.push("selected source inputs changed since review".into()); + } + if recorded.revision != current.revision + && !context.ancestor_revisions.contains(&recorded.revision) + { + reasons.push( + "reviewed revision ancestry is unknown or no longer on the current branch".into(), + ); + } + reasons +} + +fn age_limit(at: u64, plan: &QualityPlan, context: &EvaluationContext<'_>) -> Option { + match context.now_ms.checked_sub(at) { + None => Some("observation timestamp is in the future".into()), + Some(age) if plan.policy.max_age_ms.is_some_and(|max| age > max) => { + Some("observation exceeds configured maximum age".into()) + } + _ => None, + } +} + +fn check_receipt( + plan: &QualityPlan, + digest: &str, + check: &crate::CheckSpec, + receipt: &ExecutionReceipt, + context: &EvaluationContext<'_>, +) -> (CheckOutcome, Vec) { + let error = |message: &str| (CheckOutcome::Error, vec![message.to_owned()]); + if let Err(e) = receipt.validate() { + return error(&e.to_string()); + } + if receipt.plan_sha256 != digest + || receipt.subject != plan.subject + || receipt.invocation != check.invocation + { + return error("receipt plan, subject or invocation does not match the selected check"); + } + if !same_inputs(&receipt.subject.inputs, &receipt.inputs_after) { + return ( + CheckOutcome::Inconclusive, + vec!["selected inputs changed during execution".into()], + ); + } + let mut limits = context_limits(plan, context); + if let Some(age) = age_limit(receipt.finished_at_ms, plan, context) { + limits.push(age); + } + if !limits.is_empty() { + return (CheckOutcome::Inconclusive, limits); + } + if receipt.process != ProcessStatus::Completed { + let outcome = if receipt.process == ProcessStatus::Unavailable { + CheckOutcome::Skipped + } else { + CheckOutcome::Error + }; + return ( + outcome, + vec![ + receipt + .diagnostic + .clone() + .unwrap_or_else(|| "execution did not complete".into()), + ], + ); + } + if receipt.elapsed_ms > check.invocation.timeout_ms { + return error("completed execution exceeded the configured deadline"); + } + for output in receipt.stdout.iter().chain(receipt.stderr.iter()) { + if !context.verified.contains(output) { + return error("raw output artifact has not been byte-verified"); + } + } + if let Some(snapshot) = &receipt.subject.working_tree { + if !context.verified.contains(snapshot) { + return error("dirty working-tree snapshot has not been byte-verified"); + } + } + match &receipt.observed_scope { + Some(paths) if !check.scope.iter().all(|p| paths.contains(p)) => { + return ( + CheckOutcome::Inconclusive, + vec!["observed scope omits selected source inputs".into()], + ); + } + None if plan.policy.require_observed_scope => { + return ( + CheckOutcome::Inconclusive, + vec!["observed source scope is unknown".into()], + ); + } + _ => {} + } + match &check.evaluator { + Evaluator::ExitCode { success_codes } => { + if receipt.reported.is_some() { + return error("unexpected adapter assessment for an exit-code evaluator"); + } + if receipt + .exit_code + .is_some_and(|code| success_codes.contains(&code)) + { + ( + CheckOutcome::Passed, + vec!["completed exit code satisfies the configured policy".into()], + ) + } else { + ( + CheckOutcome::Blocked, + vec!["completed exit code does not satisfy the configured policy".into()], + ) + } + } + Evaluator::Reported { adapter } => { + let Some(result) = &receipt.reported else { + return error("missing required adapter assessment"); + }; + if &result.adapter != adapter || !context.verified.contains(&result.artifact) { + return error("adapter identity or verified report artifact is missing"); + } + (result.outcome, vec![result.reason.clone()]) + } + } +} + +fn referenced_check( + id: &str, + checks: &[CheckReport], + reasons: &mut Vec, + outcome: &mut CheckOutcome, +) { + if let Some(check) = checks.iter().find(|c| c.id == id) { + if check.outcome != CheckOutcome::Passed { + reasons.push(format!("referenced check {id} did not pass")); + if check.outcome == CheckOutcome::Blocked { + *outcome = CheckOutcome::Blocked; + } else if *outcome != CheckOutcome::Blocked { + *outcome = CheckOutcome::Inconclusive; + } + } + } else { + reasons.push(format!("referenced check {id} is missing")); + if *outcome != CheckOutcome::Blocked { + *outcome = CheckOutcome::Inconclusive; + } + } +} + +fn assessment_binding( + plan: &QualityPlan, + digest: &str, + subject: &Subject, + claimed: &str, + artifact: &crate::Artifact, + at: u64, + context: &EvaluationContext<'_>, +) -> Result<(), ContractError> { + crate::require( + subject == &plan.subject && claimed == digest, + "assessment plan/subject mismatch", + )?; + artifact_shape(artifact)?; + crate::require( + context.verified.contains(artifact), + "assessment artifact has not been byte-verified", + )?; + crate::require( + age_limit(at, plan, context).is_none(), + "assessment is stale or future-dated", + ) +} + +fn expectation_report( + plan: &QualityPlan, + digest: &str, + expectation: &Expectation, + checks: &[CheckReport], + runs: &BTreeMap<&str, &ExecutionReceipt>, + context: &EvaluationContext<'_>, +) -> ExpectationReport { + let mut outcome = CheckOutcome::Passed; + let mut reasons = Vec::new(); + for id in &expectation.checks { + referenced_check(id, checks, &mut reasons, &mut outcome); + } + if let Some(control) = &expectation.positive_control { + referenced_check(control, checks, &mut reasons, &mut outcome); + } + if let Some(stabilizer) = &expectation.stabilizer { + referenced_check(&stabilizer.check_id, checks, &mut reasons, &mut outcome); + if !runs + .get(stabilizer.check_id.as_str()) + .is_some_and(|r| r.observed_tests.contains(&stabilizer.test_id)) + { + reasons.push("stabilizer test was not reported as executed".into()); + if outcome != CheckOutcome::Blocked { + outcome = CheckOutcome::Inconclusive; + } + } + } + if let Some(limit) = &expectation.limitation { + reasons.push(format!("declared limitation: {limit}")); + } + if expectation.independent_audit { + let audits: Vec<_> = context + .audits + .iter() + .filter(|a| a.expectation_id == expectation.id) + .collect(); + let validation = if audits.len() != 1 { + Err(ContractError::Invalid( + "exactly one selected audit is required".into(), + )) + } else { + let a = audits[0]; + (|| { + assessment_binding( + plan, + digest, + &a.subject, + &a.plan_sha256, + &a.artifact, + a.captured_at_ms, + context, + )?; + crate::require( + nonempty(&a.observed) + && identifier(&a.producer.agent_id) + && identifier(&a.reviewer.agent_id), + "audit must identify actors and observation", + )?; + crate::require( + a.producer.agent_id != a.reviewer.agent_id + && a.producer.attempt_id != a.reviewer.attempt_id, + "audit actors and attempts must be distinct", + )?; + crate::require( + expectation.checks.iter().any(|id| { + runs.get(id.as_str()) + .is_some_and(|r| r.attempt_id == a.producer.attempt_id) + }), + "producer does not reference supporting execution", + )?; + crate::require( + !expectation.checks.contains(&a.probe_check), + "audit requires a distinct adversarial probe", + )?; + crate::require( + runs.get(a.probe_check.as_str()) + .is_some_and(|r| r.attempt_id == a.reviewer.attempt_id), + "reviewer does not reference the probe execution", + )?; + crate::require( + checks + .iter() + .any(|c| c.id == a.probe_check && c.outcome == CheckOutcome::Passed), + "adversarial probe did not complete successfully", + )?; + sealmap_corpus::route::cross_family_with( + &a.producer.model, + &a.reviewer.model, + &context.families, + ) + .map_err(|_| { + ContractError::Invalid( + "audit model-family independence is unknown or not satisfied".into(), + ) + })?; + Ok(a.verdict) + })() + }; + match validation { + Ok(AuditVerdict::Supported) => { + reasons.push("recorded independent audit supports the scoped claim".into()) + } + Ok(AuditVerdict::Contradicted) => { + outcome = CheckOutcome::Blocked; + reasons.push("auditor recorded a counterexample".into()); + } + Ok(AuditVerdict::Inconclusive) => { + if outcome != CheckOutcome::Blocked { + outcome = CheckOutcome::Inconclusive; + } + reasons.push("auditor could not conclude".into()); + } + Err(e) => { + if outcome != CheckOutcome::Blocked { + outcome = CheckOutcome::Inconclusive; + } + reasons.push(e.to_string()); + } + } + } + if expectation.category == EvidenceCategory::Manual { + let observations: Vec<_> = context + .manual_observations + .iter() + .filter(|m| m.expectation_id == expectation.id) + .collect(); + let validation = if observations.len() != 1 { + Err(ContractError::Invalid( + "exactly one selected manual observation is required".into(), + )) + } else { + let m = observations[0]; + assessment_binding( + plan, + digest, + &m.subject, + &m.plan_sha256, + &m.artifact, + m.captured_at_ms, + context, + ) + .and_then(|()| { + crate::require( + nonempty(&m.observer) && nonempty(&m.observed), + "manual observation needs an observer and observed effect", + ) + }) + .map(|()| m.verdict) + }; + match validation { + Ok(AuditVerdict::Supported) => { + reasons.push("named manual observer supports the scoped claim".into()) + } + Ok(AuditVerdict::Contradicted) => { + outcome = CheckOutcome::Blocked; + reasons.push("manual observation contradicts the claim".into()); + } + Ok(AuditVerdict::Inconclusive) => { + if outcome != CheckOutcome::Blocked { + outcome = CheckOutcome::Inconclusive; + } + reasons.push("manual observation is inconclusive".into()); + } + Err(e) => { + if outcome != CheckOutcome::Blocked { + outcome = CheckOutcome::Inconclusive; + } + reasons.push(e.to_string()); + } + } + } + ExpectationReport { + id: expectation.id.clone(), + required: expectation.required, + outcome, + reasons, + } +} + +/// Evaluate an unchanged plan against selected attempts and explicit external facts. +/// +/// No source, artifact, timestamp or command is automatically dereferenced. Choose +/// one attempt per check: historical attempts belong in the archive, not an +/// ambiguous bag from which the evaluator silently chooses the greenest result. +/// Invalid input is reported as an error; missing required evidence never passes. +pub fn evaluate( + plan: &QualityPlan, + receipts: &[ExecutionReceipt], + context: &EvaluationContext<'_>, +) -> GateReport { + let mut report = GateReport { + outcome: GateOutcome::Error, + required_checks: plan.checks.iter().filter(|c| c.required).count(), + passed_required_checks: 0, + checks: vec![], + expectations: vec![], + errors: vec![], + }; + let digest = match plan.digest() { + Ok(digest) => digest, + Err(e) => { + report.errors.push(e.to_string()); + return report; + } + }; + if let Err(e) = context.current_subject.validate() { + report.errors.push(e.to_string()); + return report; + } + let mut attempts = BTreeSet::new(); + let mut runs = BTreeMap::new(); + let ids: BTreeSet<_> = plan.checks.iter().map(|c| c.id.as_str()).collect(); + for receipt in receipts { + if !ids.contains(receipt.check_id.as_str()) { + report + .errors + .push("receipt references an unplanned check".into()); + } + if !attempts.insert(receipt.attempt_id.as_str()) { + report.errors.push("duplicate execution attempt id".into()); + } + if runs.insert(receipt.check_id.as_str(), receipt).is_some() { + report + .errors + .push("multiple attempts for one check; select an attempt explicitly".into()); + } + } + let expectation_ids: BTreeSet<_> = plan.expectations.iter().map(|e| e.id.as_str()).collect(); + for id in context + .audits + .iter() + .map(|a| a.expectation_id.as_str()) + .chain( + context + .manual_observations + .iter() + .map(|m| m.expectation_id.as_str()), + ) + { + if !expectation_ids.contains(id) { + report + .errors + .push("assessment references an unplanned expectation".into()); + } + } + for check in &plan.checks { + let run = runs.get(check.id.as_str()); + let (outcome, reasons) = match run { + Some(receipt) => check_receipt(plan, &digest, check, receipt, context), + None => ( + CheckOutcome::Inconclusive, + vec!["no execution receipt was supplied".into()], + ), + }; + if check.required && outcome == CheckOutcome::Passed { + report.passed_required_checks += 1; + } + report.checks.push(CheckReport { + id: check.id.clone(), + required: check.required, + attempt_id: run.map(|r| r.attempt_id.clone()), + outcome, + reasons, + }); + } + for expectation in &plan.expectations { + report.expectations.push(expectation_report( + plan, + &digest, + expectation, + &report.checks, + &runs, + context, + )); + } + let required: Vec<_> = report + .checks + .iter() + .filter(|r| r.required) + .map(|r| r.outcome) + .chain( + report + .expectations + .iter() + .filter(|r| r.required) + .map(|r| r.outcome), + ) + .collect(); + report.outcome = if !report.errors.is_empty() || required.contains(&CheckOutcome::Error) { + GateOutcome::Error + } else if required.contains(&CheckOutcome::Blocked) { + GateOutcome::Blocked + } else if required.iter().any(|o| *o != CheckOutcome::Passed) { + GateOutcome::Incomplete + } else { + GateOutcome::Passed + }; + report +} diff --git a/src/evidence.rs b/src/evidence.rs new file mode 100644 index 0000000..c8b0159 --- /dev/null +++ b/src/evidence.rs @@ -0,0 +1,282 @@ +//! Immutable run and audit records, with caller-supplied byte verification. + +use crate::plan::validate_inputs; +use crate::{ + Artifact, CheckOutcome, ContractError, Invocation, Subject, artifact_shape, hex, identifier, + nonempty, require, sha256, +}; +use serde::{Deserialize, Serialize}; +use std::collections::BTreeSet; + +/// What happened to the process, independently of an evaluator's verdict. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "kebab-case")] +pub enum ProcessStatus { + /// Process exited and was reaped; the exit code still needs evaluation. + Completed, + /// Required tool or execution capability was unavailable. + Unavailable, + /// Deadline elapsed and cleanup was attempted. + TimedOut, + /// Caller cancellation or signal interrupted execution. + Interrupted, + /// The child could not be started. + FailedToStart, + /// Raw output could not be captured completely or exceeded its limit. + CaptureFailed, +} + +/// Named adapter's interpretation, bound to its captured report bytes. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct ReportedResult { + /// Adapter identity expected by the plan. + pub adapter: String, + /// Completed assessment under the adapter's declared policy. + pub outcome: CheckOutcome, + /// Explanation, including threshold or interpretation limits. + pub reason: String, + /// Raw adapter report; it must be byte-verified before credit is given. + pub artifact: Artifact, +} + +/// Receipt from one explicit invocation; no field is executed by the evaluator. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct ExecutionReceipt { + /// Schema version, currently exactly 1. + pub version: u32, + /// Unique execution identity, not inferred from a filename. + pub attempt_id: String, + /// Exact typed plan digest from [`crate::QualityPlan::digest`]. + pub plan_sha256: String, + /// Check identifier within that plan. + pub check_id: String, + /// Examined source and configuration at invocation start. + pub subject: Subject, + /// Actual requested argv/environment names/resource bounds. + pub invocation: Invocation, + /// Resolved executable identity, or requested name when startup failed. + pub executable: String, + /// Optional hash of the resolved executable; not an attestation. + pub executable_sha256: Option, + /// Version reported by the tool, when available. + pub tool_version: Option, + /// Start time as milliseconds since the Unix epoch. + pub started_at_ms: u64, + /// Finish time as milliseconds since the Unix epoch. + pub finished_at_ms: u64, + /// Duration measured with a monotonic clock. + pub elapsed_ms: u64, + /// Process-level outcome, before policy interpretation. + pub process: ProcessStatus, + /// Reaped exit code when one exists. + pub exit_code: Option, + /// Terminating signal when one exists. + pub signal: Option, + /// Whether all raw output was retained within the configured bound. + pub capture_complete: bool, + /// Captured standard output, absent only when execution/capture failed. + pub stdout: Option, + /// Captured standard error, absent only when execution/capture failed. + pub stderr: Option, + /// Input hashes after execution, to detect mutation during the check. + pub inputs_after: Vec, + /// Observed source coverage; `None` explicitly means unknown. + pub observed_scope: Option>, + /// Test identifiers actually reported as executed, not just requested. + pub observed_tests: Vec, + /// Optional evidence from the evaluator named in the plan. + pub reported: Option, + /// Diagnostic for failed/skipped execution; may also describe limits. + pub diagnostic: Option, +} + +impl ExecutionReceipt { + /// Decode and validate a receipt without executing any recorded command. + /// + /// # Errors + /// Rejects malformed/unknown/duplicate fields and inconsistent process data. + pub fn parse(bytes: &[u8]) -> Result { + let receipt: Self = crate::from_json(bytes)?; + receipt.validate()?; + Ok(receipt) + } + + /// Check receipt consistency; matching a plan and bytes is a separate step. + /// + /// # Errors + /// Refuses incomplete identities, impossible timestamps and success records + /// lacking complete capture or an exit code. + pub fn validate(&self) -> Result<(), ContractError> { + require(self.version == 1, "unsupported receipt version")?; + require( + identifier(&self.attempt_id) && identifier(&self.check_id), + "invalid receipt identifier", + )?; + require(hex(&self.plan_sha256, &[64]), "invalid plan digest")?; + self.subject.validate()?; + self.invocation.validate()?; + require( + nonempty(&self.executable), + "executable identity is required", + )?; + if let Some(hash) = &self.executable_sha256 { + require(hex(hash, &[64]), "invalid executable digest")?; + } + if let Some(version) = &self.tool_version { + require(nonempty(version), "empty tool version")?; + } + require( + self.finished_at_ms >= self.started_at_ms, + "finish precedes start", + )?; + require( + !(self.exit_code.is_some() && self.signal.is_some()), + "exit code and terminating signal are mutually exclusive", + )?; + if self.process == ProcessStatus::Completed { + require( + self.exit_code.is_some() && self.signal.is_none(), + "completed execution requires an exit code", + )?; + require( + self.capture_complete && self.stdout.is_some() && self.stderr.is_some(), + "completed execution requires complete stdout/stderr", + )?; + } else { + require( + self.diagnostic.as_deref().is_some_and(nonempty), + "incomplete execution requires a diagnostic", + )?; + } + for a in self.stdout.iter().chain(self.stderr.iter()) { + artifact_shape(a)?; + } + validate_inputs(&self.inputs_after)?; + if let Some(paths) = &self.observed_scope { + let unique: BTreeSet<_> = paths.iter().collect(); + require( + unique.len() == paths.len() && paths.iter().all(|p| crate::relative_path(p)), + "invalid or duplicate observed scope", + )?; + } + let tests: BTreeSet<_> = self.observed_tests.iter().collect(); + require( + tests.len() == self.observed_tests.len() && tests.iter().all(|t| nonempty(t)), + "invalid or duplicate observed tests", + )?; + if let Some(reported) = &self.reported { + require( + identifier(&reported.adapter) && nonempty(&reported.reason), + "reported assessment requires adapter and reason", + )?; + artifact_shape(&reported.artifact)?; + } + Ok(()) + } +} + +/// Recorded actor identity. Labels alone do not attest a served model. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Actor { + /// Agent/session identity, distinct from a role name. + pub agent_id: String, + /// Execution attempt whose evidence this actor produced. + pub attempt_id: String, + /// Actual responder in Sealmap's `provider:model` syntax. + pub model: String, +} + +/// Meaning of a recorded audit/manual observation, not a general quality score. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "kebab-case")] +pub enum AuditVerdict { + /// Scoped observation supports the claim, subject to stated limits. + Supported, + /// Observation contradicts the claim. + Contradicted, + /// No supported semantic conclusion. + Inconclusive, +} + +/// Post-run assessment; keeping it outside the plan preserves plan immutability. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct AuditReceipt { + /// Expectation assessed. + pub expectation_id: String, + /// Plan to which the assessment applies. + pub plan_sha256: String, + /// Source/configuration assessed. + pub subject: Subject, + /// Evidence producer and its execution. + pub producer: Actor, + /// Independent auditor and its probe execution. + pub reviewer: Actor, + /// Distinct declared check run as the adversarial probe. + pub probe_check: String, + /// Assessment result; a required inconclusive audit is not a pass. + pub verdict: AuditVerdict, + /// Recorded claim limits and observation. + pub observed: String, + /// Raw audit output or signed/manual decision record. + pub artifact: Artifact, + /// Capture time in Unix milliseconds, used with an injected clock. + pub captured_at_ms: u64, +} + +/// Human/manual observation for a behaviour that cannot be executed here. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct ManualObservation { + /// Expectation assessed. + pub expectation_id: String, + /// Plan digest assessed. + pub plan_sha256: String, + /// Exact subject examined. + pub subject: Subject, + /// Named observer/decision reference; no authority is inferred from a name. + pub observer: String, + /// Actual state or effect observed. + pub observed: String, + /// Manual assessment. + pub verdict: AuditVerdict, + /// Raw observation record. + pub artifact: Artifact, + /// Capture time in Unix milliseconds. + pub captured_at_ms: u64, +} + +/// Exact byte references verified in memory, with no filesystem or network IO. +/// +/// Callers are responsible for resolving paths within the appropriate evidence +/// root. A hash establishes byte identity, not truth, authority or safe storage. +#[derive(Debug, Clone, Default)] +pub struct VerifiedArtifacts { + entries: BTreeSet<(String, String)>, +} + +impl VerifiedArtifacts { + /// Validate an artifact using Sealmap's contract and verify supplied bytes. + /// + /// # Errors + /// Refuses invalid paths/digests or any mismatch; does not register failures. + pub fn insert(&mut self, artifact: &Artifact, bytes: &[u8]) -> Result<(), ContractError> { + artifact_shape(artifact)?; + require( + sha256(bytes) == artifact.sha256, + "artifact bytes do not match SHA-256", + )?; + self.entries + .insert((artifact.path.clone(), artifact.sha256.clone())); + Ok(()) + } + + /// Whether this exact path and byte digest have been verified. + pub fn contains(&self, artifact: &Artifact) -> bool { + self.entries + .contains(&(artifact.path.clone(), artifact.sha256.clone())) + } +} diff --git a/src/lib.rs b/src/lib.rs new file mode 100644 index 0000000..fa60c8d --- /dev/null +++ b/src/lib.rs @@ -0,0 +1,117 @@ +//! Explicit quality contracts, without implicit execution or claims of correctness. +//! +//! The core operates on supplied data and bytes. It reads no files, queries no +//! clocks, launches no processes and makes no network calls. A passing gate means +//! the recorded policy was satisfied, not that a program is secure or deployed. +//! Finding dispositions and model-family identity use Sealmap's existing contracts. +//! +//! ``` +//! use visioncraft::{Artifact, VerifiedArtifacts}; +//! let bytes = b"recorded output\n"; +//! let artifact = Artifact { +//! path: "attempt/stdout.txt".into(), +//! sha256: visioncraft::sha256(bytes), +//! }; +//! let mut verified = VerifiedArtifacts::default(); +//! verified.insert(&artifact, bytes)?; +//! assert!(verified.contains(&artifact)); +//! # Ok::<(), visioncraft::ContractError>(()) +//! ``` + +pub mod evaluate; +pub mod evidence; +pub mod plan; + +pub use evaluate::{ + CheckOutcome, CheckReport, EvaluationContext, ExpectationReport, GateOutcome, GateReport, + evaluate, +}; +pub use evidence::{ + Actor, AuditReceipt, AuditVerdict, ExecutionReceipt, ManualObservation, ProcessStatus, + ReportedResult, VerifiedArtifacts, +}; +pub use plan::{ + CheckSpec, Evaluator, EvidenceCategory, Expectation, GatePolicy, Invocation, QualityPlan, + Stabilizer, Subject, +}; +pub use sealmap_corpus::review::Artifact; +pub use sealmap_corpus::route::FamilyCatalogue; + +use serde::de::DeserializeOwned; +use sha2::{Digest, Sha256}; + +/// Invalid input or evidence, without embedding raw document contents in errors. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum ContractError { + /// JSON could not be deserialised under the strict typed schema. + #[error("invalid JSON contract at line {line}, column {column}")] + Json { + /// One-based input line, or zero if unavailable. + line: usize, + /// Input column reported by the JSON decoder. + column: usize, + }, + /// A typed contract violates an invariant. + #[error("invalid contract: {0}")] + Invalid(String), +} + +/// Hash exact supplied bytes with the standard SHA-256 implementation. +pub fn sha256(bytes: &[u8]) -> String { + format!("{:x}", Sha256::digest(bytes)) +} + +/// Decode a typed JSON contract without including raw input in diagnostics. +/// +/// Structs in this crate reject unknown and duplicate fields. This function does +/// not replace their semantic validation methods. +/// +/// # Errors +/// Returns a location-only error when decoding fails. +pub fn from_json(bytes: &[u8]) -> Result { + serde_json::from_slice(bytes).map_err(|e| ContractError::Json { + line: e.line(), + column: e.column(), + }) +} + +pub(crate) fn require(condition: bool, message: impl Into) -> Result<(), ContractError> { + if condition { + Ok(()) + } else { + Err(ContractError::Invalid(message.into())) + } +} + +pub(crate) fn nonempty(value: &str) -> bool { + !value.trim().is_empty() && !value.contains('\0') +} + +pub(crate) fn identifier(value: &str) -> bool { + !value.is_empty() + && value.len() <= 128 + && value + .bytes() + .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_' | b'.')) +} + +pub(crate) fn hex(value: &str, lengths: &[usize]) -> bool { + lengths.contains(&value.len()) + && value + .bytes() + .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)) +} + +pub(crate) fn artifact_shape(artifact: &Artifact) -> Result<(), ContractError> { + sealmap_corpus::review::validate_artifact(artifact).map_err(|_| { + ContractError::Invalid("artifact requires a confined relative path and SHA-256".into()) + }) +} + +pub(crate) fn relative_path(path: &str) -> bool { + artifact_shape(&Artifact { + path: path.into(), + sha256: "0".repeat(64), + }) + .is_ok() +} diff --git a/src/plan.rs b/src/plan.rs new file mode 100644 index 0000000..2cd9433 --- /dev/null +++ b/src/plan.rs @@ -0,0 +1,349 @@ +//! Typed plans describe explicitly selected checks; parsing never runs them. + +use crate::{ + Artifact, ContractError, artifact_shape, from_json, hex, identifier, nonempty, relative_path, + require, sha256, +}; +use serde::{Deserialize, Serialize}; +use std::collections::BTreeSet; + +/// Immutable code and configuration identity examined by a plan. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Subject { + /// Repository/component identity, not automatically dereferenced. + pub repository: String, + /// Full lower-case Git object identifier. + pub revision: String, + /// Features, target, fixture and other relevant execution configuration. + pub configuration: String, + /// Whether the reviewed checkout contains uncommitted changes. + pub dirty: bool, + /// Exact diff/snapshot when dirty; absent for a clean checkout. + pub working_tree: Option, + /// Selected source, lockfile and configuration bytes, relative to source root. + pub inputs: Vec, +} + +impl Subject { + /// Check identity, dirty-snapshot and unique input-path requirements. + /// + /// # Errors + /// Returns an error for incomplete or malformed identities. + pub fn validate(&self) -> Result<(), ContractError> { + require(nonempty(&self.repository), "subject.repository is required")?; + require( + hex(&self.revision, &[40, 64]), + "subject.revision must be a full Git id", + )?; + require( + nonempty(&self.configuration), + "subject.configuration is required", + )?; + require( + self.dirty == self.working_tree.is_some(), + "dirty subject must have exactly one working-tree snapshot", + )?; + if let Some(a) = &self.working_tree { + artifact_shape(a)?; + } + validate_inputs(&self.inputs) + } +} + +pub(crate) fn validate_inputs(inputs: &[Artifact]) -> Result<(), ContractError> { + require(!inputs.is_empty(), "subject inputs cannot be empty")?; + let mut paths = BTreeSet::new(); + for a in inputs { + artifact_shape(a)?; + require(paths.insert(&a.path), "duplicate input path")?; + } + Ok(()) +} + +pub(crate) fn same_inputs(a: &[Artifact], b: &[Artifact]) -> bool { + let values = |items: &[Artifact]| { + items + .iter() + .map(|x| (x.path.clone(), x.sha256.clone())) + .collect::>() + }; + a.len() == b.len() && values(a) == values(b) +} + +/// An argv invocation; credentials are referred to by environment names only. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Invocation { + /// Executable name/path. No shell expansion is requested by this type. + pub program: String, + /// Literal arguments; callers must not put secrets in ordinary argv. + pub args: Vec, + /// Working directory relative to the explicitly selected workspace, or `.`. + pub cwd: String, + /// Explicit environment-variable names to pass, never their values. + pub env: Vec, + /// Whole invocation deadline in milliseconds, between 1 and 86,400,000. + pub timeout_ms: u64, + /// Combined raw output limit in bytes, between 1 and 1 GiB. + pub max_output_bytes: u64, +} + +impl Invocation { + /// Validate the bounded argv contract without resolving executables or env. + /// + /// # Errors + /// Refuses invalid paths, names, NUL bytes and absent/excessive limits. + pub fn validate(&self) -> Result<(), ContractError> { + require(nonempty(&self.program), "invocation.program is required")?; + require( + self.args.iter().all(|x| !x.contains('\0')), + "argv cannot contain NUL", + )?; + require( + self.cwd == "." || relative_path(&self.cwd), + "cwd must be a confined relative path", + )?; + let mut names = BTreeSet::new(); + for name in &self.env { + require( + name.as_bytes() + .first() + .is_some_and(|b| b.is_ascii_alphabetic() || *b == b'_') + && name.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_'), + "invalid environment name", + )?; + require(names.insert(name), "duplicate environment name")?; + } + require( + (1..=86_400_000).contains(&self.timeout_ms), + "timeout_ms outside 1..=86400000", + )?; + require( + (1..=1_073_741_824).contains(&self.max_output_bytes), + "max_output_bytes outside 1..=1073741824", + ) + } +} + +/// How a completed invocation is interpreted under an explicit policy. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(tag = "kind", rename_all = "kebab-case", deny_unknown_fields)] +pub enum Evaluator { + /// A completed, fully captured process passes for these exit codes. + ExitCode { + /// Nonempty, unique portable process exit codes in 0..=255. + success_codes: Vec, + }, + /// A named trusted adapter supplies a separate, byte-bound assessment. + Reported { + /// Exact adapter identity expected in the receipt. + adapter: String, + }, +} + +/// A check selected by the caller, with its declared source coverage. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct CheckSpec { + /// Unique plan-local identifier. + pub id: String, + /// Whether this check must pass for the aggregate gate to pass. + pub required: bool, + /// Explicit argv and resource limits. + pub invocation: Invocation, + /// Interpretation of completed output. + pub evaluator: Evaluator, + /// Nonempty subset of subject input paths claimed by this check. + pub scope: Vec, +} + +/// Type of observation needed to support an expectation. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "kebab-case")] +pub enum EvidenceCategory { + /// Scoped behaviour observed by executable checks. + Executable, + /// A plan/dry-run or other partial observation, with an explicit limitation. + PartiallyVerifiable, + /// A named observer records a manual observation, never inferred execution. + Manual, +} + +/// An automated regression reference supported by a successful check receipt. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Stabilizer { + /// Check that actually executes the regression test. + pub check_id: String, + /// Exact test identifier; the runner must report this test as executed. + pub test_id: String, +} + +/// Requirements for one behavioural expectation, separate from later evidence. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct Expectation { + /// Unique plan-local identifier. + pub id: String, + /// Plain statement judged by a reviewer, not semantically parsed by this crate. + pub claim: String, + /// Whether unmet evidence prevents the aggregate gate passing. + pub required: bool, + /// Required observation category. + pub category: EvidenceCategory, + /// Check IDs that support the expectation. + pub checks: Vec, + /// Requires a linked, executed regression test. + pub regression_critical: bool, + /// Actual regression test reference, required when regression-critical. + pub stabilizer: Option, + /// A distinct successful check that guards against reject-everything fixtures. + pub positive_control: Option, + /// Requires a distinct agent/model-family auditor and a separate probe. + pub independent_audit: bool, + /// Scope caveat, mandatory for partial or manual evidence. + pub limitation: Option, +} + +/// Policies explicitly chosen for this plan, rather than universal thresholds. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct GatePolicy { + /// Maximum observation age in milliseconds; absent means no age limit. + pub max_age_ms: Option, + /// Require an observed source scope that covers each check's declared scope. + pub require_observed_scope: bool, +} + +/// Version-one plan; all output evidence is stored separately from this input. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct QualityPlan { + /// Schema version, currently exactly 1. + pub version: u32, + /// Human-selected identifier for this bounded quality plan. + pub id: String, + /// Exact source/configuration scope. + pub subject: Subject, + /// Nonempty checks, with at least one required check. + pub checks: Vec, + /// Optional expectations; small routine changes need no invented ledger. + pub expectations: Vec, + /// Explicit freshness and observed-coverage policy. + pub policy: GatePolicy, +} + +impl QualityPlan { + /// Decode and validate a plan. Never executes its invocations. + /// + /// # Errors + /// Refuses invalid JSON, unknown/duplicate fields and contract violations. + pub fn parse(bytes: &[u8]) -> Result { + let plan: Self = from_json(bytes)?; + plan.validate()?; + Ok(plan) + } + + /// Validate identifiers, references and bounded execution policies. + /// + /// # Errors + /// Returns the first contract violation, without reading external resources. + pub fn validate(&self) -> Result<(), ContractError> { + require(self.version == 1, "unsupported plan version")?; + require(identifier(&self.id), "invalid plan id")?; + self.subject.validate()?; + require( + !self.checks.is_empty() && self.checks.iter().any(|c| c.required), + "a gate requires at least one required check", + )?; + require( + self.policy.max_age_ms != Some(0), + "max_age_ms must be positive when present", + )?; + let inputs: BTreeSet<_> = self.subject.inputs.iter().map(|x| &x.path).collect(); + let mut ids = BTreeSet::new(); + for c in &self.checks { + require( + identifier(&c.id) && ids.insert(&c.id), + "invalid or duplicate check id", + )?; + c.invocation.validate()?; + require(!c.scope.is_empty(), "check scope cannot be empty")?; + let mut scope = BTreeSet::new(); + for p in &c.scope { + require( + inputs.contains(p) && scope.insert(p), + "scope must uniquely reference subject inputs", + )?; + } + match &c.evaluator { + Evaluator::ExitCode { success_codes } => { + let codes: BTreeSet<_> = success_codes.iter().collect(); + require( + !codes.is_empty() + && codes.len() == success_codes.len() + && success_codes.iter().all(|c| (0..=255).contains(c)), + "success_codes must be unique portable exit codes", + )?; + } + Evaluator::Reported { adapter } => require( + identifier(adapter), + "reported evaluator requires an adapter id", + )?, + } + } + let mut expectations = BTreeSet::new(); + for e in &self.expectations { + require( + identifier(&e.id) && expectations.insert(&e.id), + "invalid or duplicate expectation id", + )?; + require(nonempty(&e.claim), "expectation claim is required")?; + let checks: BTreeSet<_> = e.checks.iter().collect(); + require( + !checks.is_empty() + && checks.len() == e.checks.len() + && checks.iter().all(|c| ids.contains(c)), + "expectation must uniquely reference declared checks", + )?; + require( + !e.regression_critical || e.stabilizer.is_some(), + "regression-critical expectation requires a stabilizer", + )?; + if let Some(s) = &e.stabilizer { + require( + ids.contains(&s.check_id) && nonempty(&s.test_id), + "invalid stabilizer reference", + )?; + } + if let Some(c) = &e.positive_control { + require( + ids.contains(c) && !checks.contains(c), + "positive control must be a distinct declared check", + )?; + } + if e.category != EvidenceCategory::Executable { + require( + e.limitation.as_deref().is_some_and(nonempty), + "partial/manual evidence requires a limitation", + )?; + } + } + Ok(()) + } + + /// SHA-256 of the validated, deterministically serialised typed plan. + /// + /// Whitespace in input JSON is irrelevant; every typed field and vector order + /// contributes. This is a content binding, not a signature or authority grant. + /// + /// # Errors + /// Refuses invalid plans or serialization failures. + pub fn digest(&self) -> Result { + self.validate()?; + let bytes = serde_json::to_vec(self) + .map_err(|_| ContractError::Invalid("plan serialization failed".into()))?; + Ok(sha256(&bytes)) + } +} From 209bb04b7a14ad3102b2d1872d47cec85a13e632 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 3 Nov 2026 10:38:04 +0000 Subject: [PATCH 02/16] Exercise evidence boundaries and retain honest incomplete outcomes --- src/evaluate.rs | 90 +++++-- src/evidence.rs | 24 +- src/plan.rs | 41 +++- tests/core.rs | 634 ++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 758 insertions(+), 31 deletions(-) create mode 100644 tests/core.rs diff --git a/src/evaluate.rs b/src/evaluate.rs index 9f757b9..0501c85 100644 --- a/src/evaluate.rs +++ b/src/evaluate.rs @@ -206,11 +206,20 @@ fn check_receipt( if receipt.elapsed_ms > check.invocation.timeout_ms { return error("completed execution exceeded the configured deadline"); } + let mut output_bytes = 0u64; for output in receipt.stdout.iter().chain(receipt.stderr.iter()) { - if !context.verified.contains(output) { + if let Some(bytes) = context.verified.byte_len(output) { + let Some(total) = output_bytes.checked_add(bytes) else { + return error("output length overflow"); + }; + output_bytes = total; + } else { return error("raw output artifact has not been byte-verified"); } } + if output_bytes > check.invocation.max_output_bytes { + return error("verified raw output exceeds configured capture limit"); + } if let Some(snapshot) = &receipt.subject.working_tree { if !context.verified.contains(snapshot) { return error("dirty working-tree snapshot has not been byte-verified"); @@ -341,7 +350,12 @@ fn expectation_report( if let Some(limit) = &expectation.limitation { reasons.push(format!("declared limitation: {limit}")); } - if expectation.independent_audit { + if expectation.independent_audit + || context + .audits + .iter() + .any(|a| a.expectation_id == expectation.id) + { let audits: Vec<_> = context .audits .iter() @@ -376,8 +390,10 @@ fn expectation_report( )?; crate::require( expectation.checks.iter().any(|id| { - runs.get(id.as_str()) - .is_some_and(|r| r.attempt_id == a.producer.attempt_id) + runs.get(id.as_str()).is_some_and(|r| { + r.attempt_id == a.producer.attempt_id + && r.finished_at_ms <= a.captured_at_ms + }) }), "producer does not reference supporting execution", )?; @@ -386,33 +402,45 @@ fn expectation_report( "audit requires a distinct adversarial probe", )?; crate::require( - runs.get(a.probe_check.as_str()) - .is_some_and(|r| r.attempt_id == a.reviewer.attempt_id), + runs.get(a.probe_check.as_str()).is_some_and(|r| { + r.attempt_id == a.reviewer.attempt_id + && r.finished_at_ms <= a.captured_at_ms + }), "reviewer does not reference the probe execution", )?; crate::require( - checks - .iter() - .any(|c| c.id == a.probe_check && c.outcome == CheckOutcome::Passed), + checks.iter().any(|c| { + c.id == a.probe_check + && (c.outcome == CheckOutcome::Passed + || (a.verdict == AuditVerdict::Contradicted + && c.outcome == CheckOutcome::Blocked)) + }), "adversarial probe did not complete successfully", )?; - sealmap_corpus::route::cross_family_with( - &a.producer.model, - &a.reviewer.model, - &context.families, - ) - .map_err(|_| { - ContractError::Invalid( - "audit model-family independence is unknown or not satisfied".into(), + if expectation.independent_audit { + sealmap_corpus::route::cross_family_with( + &a.producer.model, + &a.reviewer.model, + &context.families, ) - })?; + .map_err(|_| { + ContractError::Invalid( + "audit model-family independence is unknown or not satisfied".into(), + ) + })?; + } Ok(a.verdict) })() }; match validation { - Ok(AuditVerdict::Supported) => { - reasons.push("recorded independent audit supports the scoped claim".into()) - } + Ok(AuditVerdict::Supported) => reasons.push( + if expectation.independent_audit { + "recorded independent audit supports the scoped claim" + } else { + "recorded audit supports the scoped claim; model independence was not required" + } + .into(), + ), Ok(AuditVerdict::Contradicted) => { outcome = CheckOutcome::Blocked; reasons.push("auditor recorded a counterexample".into()); @@ -431,7 +459,12 @@ fn expectation_report( } } } - if expectation.category == EvidenceCategory::Manual { + if expectation.category == EvidenceCategory::Manual + || context + .manual_observations + .iter() + .any(|m| m.expectation_id == expectation.id) + { let observations: Vec<_> = context .manual_observations .iter() @@ -524,6 +557,19 @@ pub fn evaluate( let mut runs = BTreeMap::new(); let ids: BTreeSet<_> = plan.checks.iter().map(|c| c.id.as_str()).collect(); for receipt in receipts { + if let Err(error) = receipt.validate() { + report.errors.push(error.to_string()); + } + if let Some(check) = plan.checks.iter().find(|c| c.id == receipt.check_id) { + if receipt.plan_sha256 != digest + || receipt.subject != plan.subject + || receipt.invocation != check.invocation + { + report + .errors + .push("receipt does not bind to its declared plan/subject/invocation".into()); + } + } if !ids.contains(receipt.check_id.as_str()) { report .errors diff --git a/src/evidence.rs b/src/evidence.rs index c8b0159..fd04a48 100644 --- a/src/evidence.rs +++ b/src/evidence.rs @@ -1,12 +1,12 @@ //! Immutable run and audit records, with caller-supplied byte verification. -use crate::plan::validate_inputs; +use crate::plan::validate_input_paths; use crate::{ Artifact, CheckOutcome, ContractError, Invocation, Subject, artifact_shape, hex, identifier, nonempty, require, sha256, }; use serde::{Deserialize, Serialize}; -use std::collections::BTreeSet; +use std::collections::{BTreeMap, BTreeSet}; /// What happened to the process, independently of an evaluator's verdict. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] @@ -81,6 +81,7 @@ pub struct ExecutionReceipt { /// Captured standard error, absent only when execution/capture failed. pub stderr: Option, /// Input hashes after execution, to detect mutation during the check. + /// Empty records deletion of every selected input, never successful stability. pub inputs_after: Vec, /// Observed source coverage; `None` explicitly means unknown. pub observed_scope: Option>, @@ -153,7 +154,7 @@ impl ExecutionReceipt { for a in self.stdout.iter().chain(self.stderr.iter()) { artifact_shape(a)?; } - validate_inputs(&self.inputs_after)?; + validate_input_paths(&self.inputs_after)?; if let Some(paths) = &self.observed_scope { let unique: BTreeSet<_> = paths.iter().collect(); require( @@ -255,7 +256,7 @@ pub struct ManualObservation { /// root. A hash establishes byte identity, not truth, authority or safe storage. #[derive(Debug, Clone, Default)] pub struct VerifiedArtifacts { - entries: BTreeSet<(String, String)>, + entries: BTreeMap<(String, String), u64>, } impl VerifiedArtifacts { @@ -269,14 +270,23 @@ impl VerifiedArtifacts { sha256(bytes) == artifact.sha256, "artifact bytes do not match SHA-256", )?; - self.entries - .insert((artifact.path.clone(), artifact.sha256.clone())); + self.entries.insert( + (artifact.path.clone(), artifact.sha256.clone()), + bytes.len() as u64, + ); Ok(()) } /// Whether this exact path and byte digest have been verified. pub fn contains(&self, artifact: &Artifact) -> bool { self.entries - .contains(&(artifact.path.clone(), artifact.sha256.clone())) + .contains_key(&(artifact.path.clone(), artifact.sha256.clone())) + } + + /// Byte length of an exact verified artifact, not a claimed receipt length. + pub fn byte_len(&self, artifact: &Artifact) -> Option { + self.entries + .get(&(artifact.path.clone(), artifact.sha256.clone())) + .copied() } } diff --git a/src/plan.rs b/src/plan.rs index 2cd9433..97ed084 100644 --- a/src/plan.rs +++ b/src/plan.rs @@ -53,6 +53,10 @@ impl Subject { pub(crate) fn validate_inputs(inputs: &[Artifact]) -> Result<(), ContractError> { require(!inputs.is_empty(), "subject inputs cannot be empty")?; + validate_input_paths(inputs) +} + +pub(crate) fn validate_input_paths(inputs: &[Artifact]) -> Result<(), ContractError> { let mut paths = BTreeSet::new(); for a in inputs { artifact_shape(a)?; @@ -192,7 +196,8 @@ pub struct Expectation { pub required: bool, /// Required observation category. pub category: EvidenceCategory, - /// Check IDs that support the expectation. + /// Check IDs that support the expectation. May be empty only for a manual + /// expectation without a required model audit. pub checks: Vec, /// Requires a linked, executed regression test. pub regression_critical: bool, @@ -239,6 +244,37 @@ impl QualityPlan { /// /// # Errors /// Refuses invalid JSON, unknown/duplicate fields and contract violations. + /// + /// # Examples + /// + /// This records a check; it does not run `cargo` or inspect the claimed source. + /// Source hashes here illustrate the shape and must be replaced by actual + /// selected bytes before producing execution receipts. + /// + /// ``` + /// use visioncraft::QualityPlan; + /// let plan = QualityPlan::parse(br#"{ + /// "version": 1, "id": "unit-contract", + /// "subject": { + /// "repository": "example", "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + /// "configuration": "default features", "dirty": false, "working_tree": null, + /// "inputs": [{"path": "src/lib.rs", + /// "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}] + /// }, + /// "checks": [{ + /// "id": "unit", "required": true, + /// "invocation": {"program": "cargo", "args": ["test"], "cwd": ".", + /// "env": ["PATH"], "timeout_ms": 60000, "max_output_bytes": 1048576}, + /// "evaluator": {"kind": "exit-code", "success_codes": [0]}, + /// "scope": ["src/lib.rs"] + /// }], + /// "expectations": [], + /// "policy": {"max_age_ms": 86400000, "require_observed_scope": false} + /// }"#)?; + /// assert_eq!(plan.checks[0].id, "unit"); + /// assert_eq!(plan.digest()?.len(), 64); + /// # Ok::<(), visioncraft::ContractError>(()) + /// ``` pub fn parse(bytes: &[u8]) -> Result { let plan: Self = from_json(bytes)?; plan.validate()?; @@ -302,7 +338,8 @@ impl QualityPlan { require(nonempty(&e.claim), "expectation claim is required")?; let checks: BTreeSet<_> = e.checks.iter().collect(); require( - !checks.is_empty() + (!checks.is_empty() + || (e.category == EvidenceCategory::Manual && !e.independent_audit)) && checks.len() == e.checks.len() && checks.iter().all(|c| ids.contains(c)), "expectation must uniquely reference declared checks", diff --git a/tests/core.rs b/tests/core.rs new file mode 100644 index 0000000..eba222d --- /dev/null +++ b/tests/core.rs @@ -0,0 +1,634 @@ +//! Offline contract probes: no child processes, filesystem fixtures or models. +use visioncraft::*; + +fn artifact(path: &str, bytes: &[u8]) -> Artifact { + Artifact { + path: path.into(), + sha256: sha256(bytes), + } +} + +fn plan() -> QualityPlan { + let invocation = Invocation { + program: "cargo".into(), + args: vec!["test".into()], + cwd: ".".into(), + env: vec!["PATH".into()], + timeout_ms: 1000, + max_output_bytes: 1024, + }; + QualityPlan { + version: 1, + id: "quality".into(), + subject: Subject { + repository: "example".into(), + revision: "a".repeat(40), + configuration: "default features; unit fixture".into(), + dirty: false, + working_tree: None, + inputs: vec![artifact("src/lib.rs", b"fn implementation() {}")], + }, + checks: ["main", "control", "probe"] + .into_iter() + .map(|id| CheckSpec { + id: id.into(), + required: id == "main", + invocation: invocation.clone(), + evaluator: Evaluator::ExitCode { + success_codes: vec![0], + }, + scope: vec!["src/lib.rs".into()], + }) + .collect(), + expectations: vec![], + policy: GatePolicy { + max_age_ms: Some(1000), + require_observed_scope: true, + }, + } +} + +fn receipt(plan: &QualityPlan, id: &str, verified: &mut VerifiedArtifacts) -> ExecutionReceipt { + let stdout = artifact(&format!("{id}/stdout.txt"), b"ok\n"); + let stderr = artifact(&format!("{id}/stderr.txt"), b""); + verified.insert(&stdout, b"ok\n").unwrap(); + verified.insert(&stderr, b"").unwrap(); + ExecutionReceipt { + version: 1, + attempt_id: format!("attempt-{id}"), + plan_sha256: plan.digest().unwrap(), + check_id: id.into(), + subject: plan.subject.clone(), + invocation: plan + .checks + .iter() + .find(|c| c.id == id) + .unwrap() + .invocation + .clone(), + executable: "/usr/bin/cargo".into(), + executable_sha256: None, + tool_version: Some("fixture-1".into()), + started_at_ms: 1000, + finished_at_ms: 1010, + elapsed_ms: 10, + process: ProcessStatus::Completed, + exit_code: Some(0), + signal: None, + capture_complete: true, + stdout: Some(stdout), + stderr: Some(stderr), + inputs_after: plan.subject.inputs.clone(), + observed_scope: Some(vec!["src/lib.rs".into()]), + observed_tests: vec!["unit::contract".into()], + reported: None, + diagnostic: None, + } +} + +fn expectation() -> Expectation { + Expectation { + id: "EXP-001".into(), + claim: "the scoped contract holds".into(), + required: true, + category: EvidenceCategory::Executable, + checks: vec!["main".into()], + regression_critical: true, + stabilizer: Some(Stabilizer { + check_id: "main".into(), + test_id: "unit::contract".into(), + }), + positive_control: Some("control".into()), + independent_audit: false, + limitation: None, + } +} + +fn report( + plan: &QualityPlan, + receipts: &[ExecutionReceipt], + verified: &VerifiedArtifacts, +) -> GateReport { + evaluate( + plan, + receipts, + &EvaluationContext::new(1020, &plan.subject, verified), + ) +} + +fn audit(plan: &QualityPlan, verified: &mut VerifiedArtifacts) -> AuditReceipt { + let artifact = artifact("audit.txt", b"independent scoped observation"); + verified + .insert(&artifact, b"independent scoped observation") + .unwrap(); + AuditReceipt { + expectation_id: "EXP-001".into(), + plan_sha256: plan.digest().unwrap(), + subject: plan.subject.clone(), + producer: Actor { + agent_id: "producer".into(), + attempt_id: "attempt-main".into(), + model: "gateway:claude-sonnet".into(), + }, + reviewer: Actor { + agent_id: "reviewer".into(), + attempt_id: "attempt-probe".into(), + model: "gateway:gpt-6-astra".into(), + }, + probe_check: "probe".into(), + verdict: AuditVerdict::Supported, + observed: "control and counterexample probe executed".into(), + artifact, + captured_at_ms: 1015, + } +} + +#[test] +fn normal_receipts_pass_without_optional_runs_or_an_expectation_ledger() { + let plan = plan(); + let mut verified = VerifiedArtifacts::default(); + let run = receipt(&plan, "main", &mut verified); + let report = report(&plan, &[run], &verified); + assert!(report.passed(), "{report:?}"); + assert_eq!(report.required_checks, 1); + assert_eq!(report.passed_required_checks, 1); + assert_eq!(report.checks.len(), 3); + assert!(report.expectations.is_empty()); +} + +#[test] +fn missing_incomplete_and_failed_checks_cannot_be_required_passes() { + let plan = plan(); + let mut verified = VerifiedArtifacts::default(); + assert_eq!( + report(&plan, &[], &verified).outcome, + GateOutcome::Incomplete + ); + for status in [ + ProcessStatus::Unavailable, + ProcessStatus::TimedOut, + ProcessStatus::Interrupted, + ProcessStatus::FailedToStart, + ProcessStatus::CaptureFailed, + ] { + let mut run = receipt(&plan, "main", &mut verified); + run.process = status; + run.diagnostic = Some("fixture could not execute to completion".into()); + run.capture_complete = false; + assert!(!report(&plan, &[run], &verified).passed(), "{status:?}"); + } + let mut run = receipt(&plan, "main", &mut verified); + run.exit_code = Some(1); + assert_eq!( + report(&plan, &[run], &verified).outcome, + GateOutcome::Blocked + ); +} + +#[test] +fn optional_failure_remains_visible_without_changing_the_denominator() { + let plan = plan(); + let mut verified = VerifiedArtifacts::default(); + let main = receipt(&plan, "main", &mut verified); + let mut optional = receipt(&plan, "probe", &mut verified); + optional.exit_code = Some(1); + let report = report(&plan, &[main, optional], &verified); + assert!(report.passed()); + assert_eq!(report.checks[2].outcome, CheckOutcome::Blocked); + assert_eq!(report.required_checks, 1); +} + +#[test] +fn changing_policy_subject_or_argv_cannot_reuse_an_old_pass() { + let original = plan(); + let mut verified = VerifiedArtifacts::default(); + let run = receipt(&original, "main", &mut verified); + for case in 0..3 { + let mut changed = original.clone(); + match case { + 0 => changed.policy.require_observed_scope = false, + 1 => changed.subject.configuration.push_str(" other"), + _ => changed.checks[0].invocation.args.push("--release".into()), + } + assert_eq!( + report(&changed, std::slice::from_ref(&run), &verified).outcome, + GateOutcome::Error + ); + } + for case in 0..3 { + let mut changed = run.clone(); + match case { + 0 => changed.plan_sha256 = "b".repeat(64), + 1 => changed.subject.revision = "b".repeat(40), + _ => changed.invocation.args.push("--release".into()), + } + assert_eq!( + report(&original, &[changed], &verified).outcome, + GateOutcome::Error + ); + } +} + +#[test] +fn output_hashes_are_required_and_mutated_bytes_never_verify() { + let plan = plan(); + let mut verified = VerifiedArtifacts::default(); + let run = receipt(&plan, "main", &mut verified); + assert_eq!( + report( + &plan, + std::slice::from_ref(&run), + &VerifiedArtifacts::default() + ) + .outcome, + GateOutcome::Error + ); + let mut bad = VerifiedArtifacts::default(); + assert!( + bad.insert(run.stdout.as_ref().unwrap(), b"different") + .is_err() + ); + assert!(!bad.contains(run.stdout.as_ref().unwrap())); + assert!(report(&plan, &[run], &verified).passed()); +} + +#[test] +fn exceeding_output_limit_cannot_be_hidden_by_capture_complete() { + let mut plan = plan(); + plan.checks[0].invocation.max_output_bytes = 2; + let mut verified = VerifiedArtifacts::default(); + let run = receipt(&plan, "main", &mut verified); // stdout is 3 actual bytes. + assert_eq!(report(&plan, &[run], &verified).outcome, GateOutcome::Error); +} + +#[test] +fn deleted_all_selected_inputs_remains_an_honest_mutation_receipt() { + let plan = plan(); + let mut verified = VerifiedArtifacts::default(); + let mut run = receipt(&plan, "main", &mut verified); + run.inputs_after.clear(); + run.validate().unwrap(); + assert_eq!( + report(&plan, &[run], &verified).outcome, + GateOutcome::Incomplete + ); +} + +#[test] +fn duplicate_attempts_and_unknown_check_ids_are_not_silently_selected() { + let plan = plan(); + let mut verified = VerifiedArtifacts::default(); + let run = receipt(&plan, "main", &mut verified); + assert_eq!( + report(&plan, &[run.clone(), run.clone()], &verified).outcome, + GateOutcome::Error + ); + let mut unknown = run.clone(); + unknown.check_id = "not-planned".into(); + assert_eq!( + report(&plan, &[run, unknown], &verified).outcome, + GateOutcome::Error + ); +} + +#[test] +fn known_partial_scope_and_required_unknown_scope_do_not_pass() { + let plan = plan(); + let mut verified = VerifiedArtifacts::default(); + for scope in [None, Some(vec![])] { + let mut run = receipt(&plan, "main", &mut verified); + run.observed_scope = scope; + assert_eq!( + report(&plan, &[run], &verified).outcome, + GateOutcome::Incomplete + ); + } + let mut tolerant = plan.clone(); + tolerant.policy.require_observed_scope = false; + let mut run = receipt(&tolerant, "main", &mut verified); + run.observed_scope = None; + assert!(report(&tolerant, &[run], &verified).passed()); +} + +#[test] +fn freshness_uses_injected_clock_and_relevant_bytes_not_unrelated_head_changes() { + let plan = plan(); + let mut verified = VerifiedArtifacts::default(); + let run = receipt(&plan, "main", &mut verified); + assert!( + evaluate( + &plan, + std::slice::from_ref(&run), + &EvaluationContext::new(2010, &plan.subject, &verified) + ) + .passed() + ); + for now in [1009, 2011] { + assert_eq!( + evaluate( + &plan, + std::slice::from_ref(&run), + &EvaluationContext::new(now, &plan.subject, &verified) + ) + .outcome, + GateOutcome::Incomplete + ); + } + let mut current = plan.subject.clone(); + current.revision = "b".repeat(40); + let ancestry = [plan.subject.revision.clone()]; + let mut context = EvaluationContext::new(1020, ¤t, &verified); + assert_eq!( + evaluate(&plan, std::slice::from_ref(&run), &context).outcome, + GateOutcome::Incomplete + ); + context.ancestor_revisions = &ancestry; + assert!(evaluate(&plan, std::slice::from_ref(&run), &context).passed()); + current.inputs[0].sha256 = "c".repeat(64); + let mut context = EvaluationContext::new(1020, ¤t, &verified); + context.ancestor_revisions = &ancestry; + assert_eq!( + evaluate(&plan, &[run], &context).outcome, + GateOutcome::Incomplete + ); +} + +#[test] +fn malformed_and_unknown_json_never_echoes_source_values() { + let json = serde_json::to_string(&plan()).unwrap(); + for invalid in [ + json.replacen("{", "{\"secret-SENTINEL\":1,", 1), + json.replacen("\"version\":1", "\"version\":1,\"version\":1", 1), + "{\"version\":\"private-SENTINEL\"}".into(), + ] { + let error = QualityPlan::parse(invalid.as_bytes()) + .unwrap_err() + .to_string(); + assert!(!error.contains("SENTINEL")); + } + let mut empty = plan(); + empty.checks.clear(); + assert!(empty.validate().is_err()); + let mut optional = plan(); + for c in &mut optional.checks { + c.required = false; + } + assert!(optional.validate().is_err()); + let mut duplicate = plan(); + duplicate.checks.push(duplicate.checks[0].clone()); + assert!(duplicate.validate().is_err()); +} + +#[test] +fn policy_references_and_resource_limits_are_strict() { + for case in 0..7 { + let mut plan = plan(); + match case { + 0 => plan.checks[0].invocation.timeout_ms = 0, + 1 => plan.checks[0].invocation.max_output_bytes = u64::MAX, + 2 => plan.checks[0].invocation.cwd = "../outside".into(), + 3 => plan.checks[0].scope = vec!["missing.rs".into()], + 4 => plan.subject.inputs.push(plan.subject.inputs[0].clone()), + 5 => plan.subject.dirty = true, + _ => { + plan.checks[0].evaluator = Evaluator::ExitCode { + success_codes: vec![0, 0], + } + } + } + assert!(plan.validate().is_err(), "case {case}"); + } +} + +#[test] +fn stabilisation_needs_an_executed_test_and_a_successful_distinct_control() { + let mut plan = plan(); + plan.expectations.push(expectation()); + let mut verified = VerifiedArtifacts::default(); + let mut runs = vec![ + receipt(&plan, "main", &mut verified), + receipt(&plan, "control", &mut verified), + ]; + assert!(report(&plan, &runs, &verified).passed()); + runs[0].observed_tests.clear(); + assert_eq!( + report(&plan, &runs, &verified).outcome, + GateOutcome::Incomplete + ); + runs[0].observed_tests.push("unit::contract".into()); + runs[1].exit_code = Some(1); + assert_eq!( + report(&plan, &runs, &verified).outcome, + GateOutcome::Blocked + ); + plan.expectations[0].positive_control = Some("main".into()); + assert!(plan.validate().is_err()); +} + +#[test] +fn model_independence_uses_actual_families_and_binds_actor_attempts() { + let mut plan = plan(); + let mut expectation = expectation(); + expectation.independent_audit = true; + plan.expectations.push(expectation); + let mut verified = VerifiedArtifacts::default(); + let runs = ["main", "control", "probe"].map(|id| receipt(&plan, id, &mut verified)); + let valid = audit(&plan, &mut verified); + let context = EvaluationContext::new(1020, &plan.subject, &verified); + assert_eq!( + evaluate(&plan, &runs, &context).outcome, + GateOutcome::Incomplete + ); + for case in 0..5 { + let mut audit = valid.clone(); + match case { + 0 => audit.reviewer.model = "other:claude-opus".into(), + 1 => audit.reviewer.model = "gateway:unknown".into(), + 2 => audit.reviewer.agent_id = audit.producer.agent_id.clone(), + 3 => audit.reviewer.attempt_id = "unrelated-attempt".into(), + _ => audit.plan_sha256 = "0".repeat(64), + } + let audits = [audit]; + let mut context = EvaluationContext::new(1020, &plan.subject, &verified); + context.audits = &audits; + assert_eq!( + evaluate(&plan, &runs, &context).outcome, + GateOutcome::Incomplete, + "case {case}" + ); + } + let audits = [valid]; + let mut context = EvaluationContext::new(1020, &plan.subject, &verified); + context.audits = &audits; + assert!(evaluate(&plan, &runs, &context).passed()); +} + +#[test] +fn a_completed_counterexample_probe_blocks_even_when_its_test_assertion_failed() { + let mut plan = plan(); + let mut expectation = expectation(); + expectation.independent_audit = true; + plan.expectations.push(expectation); + let mut verified = VerifiedArtifacts::default(); + let mut runs = ["main", "control", "probe"].map(|id| receipt(&plan, id, &mut verified)); + runs[2].exit_code = Some(1); + let mut audit = audit(&plan, &mut verified); + audit.verdict = AuditVerdict::Contradicted; + let audits = [audit]; + let mut context = EvaluationContext::new(1020, &plan.subject, &verified); + context.audits = &audits; + assert_eq!( + evaluate(&plan, &runs, &context).outcome, + GateOutcome::Blocked + ); +} + +#[test] +fn manual_observations_require_a_bound_named_observation_not_a_boolean_claim() { + let mut plan = plan(); + let mut e = expectation(); + e.category = EvidenceCategory::Manual; + e.limitation = Some("device requires manual observation".into()); + plan.expectations.push(e); + let mut verified = VerifiedArtifacts::default(); + let runs = ["main", "control"].map(|id| receipt(&plan, id, &mut verified)); + assert_eq!( + report(&plan, &runs, &verified).outcome, + GateOutcome::Incomplete + ); + let artifact = artifact("human.txt", b"observed state"); + verified.insert(&artifact, b"observed state").unwrap(); + let observation = ManualObservation { + expectation_id: "EXP-001".into(), + plan_sha256: plan.digest().unwrap(), + subject: plan.subject.clone(), + observer: "operator receipt #1".into(), + observed: "rendering observed on named device".into(), + verdict: AuditVerdict::Supported, + artifact, + captured_at_ms: 1010, + }; + let observations = [observation]; + let mut context = EvaluationContext::new(1020, &plan.subject, &verified); + context.manual_observations = &observations; + assert!(evaluate(&plan, &runs, &context).passed()); +} + +#[test] +fn reported_evaluators_need_the_exact_adapter_and_verified_raw_report() { + let mut plan = plan(); + plan.checks[0].evaluator = Evaluator::Reported { + adapter: "fixture-review".into(), + }; + let mut verified = VerifiedArtifacts::default(); + let mut run = receipt(&plan, "main", &mut verified); + assert_eq!( + report(&plan, std::slice::from_ref(&run), &verified).outcome, + GateOutcome::Error + ); + let artifact = artifact("review.json", b"{\"completed\":true}"); + run.reported = Some(ReportedResult { + adapter: "fixture-review".into(), + outcome: CheckOutcome::Passed, + reason: "lower-priority findings remain below configured threshold".into(), + artifact: artifact.clone(), + }); + assert_eq!( + report(&plan, std::slice::from_ref(&run), &verified).outcome, + GateOutcome::Error + ); + verified.insert(&artifact, b"{\"completed\":true}").unwrap(); + assert!(report(&plan, &[run], &verified).passed()); +} + +#[test] +fn hash_vector_and_literal_command_contract_do_not_require_runtime_access() { + assert_eq!( + sha256(b"abc"), + "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad" + ); + let mut plan = plan(); + plan.checks[0].invocation.args = vec!["$(do-not-execute); `nor-this`".into()]; + let mut verified = VerifiedArtifacts::default(); + let run = receipt(&plan, "main", &mut verified); + let roundtrip = QualityPlan::parse(&serde_json::to_vec(&plan).unwrap()).unwrap(); + assert_eq!(plan.digest().unwrap(), roundtrip.digest().unwrap()); + assert!(report(&plan, &[run], &verified).passed()); +} + +#[test] +fn optional_contract_corruption_is_an_input_error_not_an_optional_failure() { + let plan = plan(); + let mut verified = VerifiedArtifacts::default(); + let main = receipt(&plan, "main", &mut verified); + let mut invalid = receipt(&plan, "probe", &mut verified); + invalid.exit_code = None; + assert_eq!( + report(&plan, &[main, invalid], &verified).outcome, + GateOutcome::Error + ); +} + +#[test] +fn audit_cannot_predate_the_executions_it_claims_to_have_observed() { + let mut plan = plan(); + let mut e = expectation(); + e.independent_audit = true; + plan.expectations.push(e); + let mut verified = VerifiedArtifacts::default(); + let runs = ["main", "control", "probe"].map(|id| receipt(&plan, id, &mut verified)); + let mut audit = audit(&plan, &mut verified); + audit.captured_at_ms = 1001; + let audits = [audit]; + let mut context = EvaluationContext::new(1020, &plan.subject, &verified); + context.audits = &audits; + assert_eq!( + evaluate(&plan, &runs, &context).outcome, + GateOutcome::Incomplete + ); +} + +#[test] +fn a_manual_expectation_does_not_need_a_fabricated_executable_scenario() { + let mut plan = plan(); + let mut e = expectation(); + e.category = EvidenceCategory::Manual; + e.limitation = Some("requires physical observation".into()); + e.checks.clear(); + e.regression_critical = false; + e.stabilizer = None; + e.positive_control = None; + plan.expectations.push(e); + plan.validate().unwrap(); + let mut verified = VerifiedArtifacts::default(); + let run = receipt(&plan, "main", &mut verified); + let artifact = artifact("manual.txt", b"physical observation"); + verified.insert(&artifact, b"physical observation").unwrap(); + let observations = [ManualObservation { + expectation_id: "EXP-001".into(), + plan_sha256: plan.digest().unwrap(), + subject: plan.subject.clone(), + observer: "operator observation #2".into(), + observed: "device inspection".into(), + verdict: AuditVerdict::Supported, + artifact, + captured_at_ms: 1010, + }]; + let mut context = EvaluationContext::new(1020, &plan.subject, &verified); + context.manual_observations = &observations; + assert!(evaluate(&plan, &[run], &context).passed()); +} + +#[test] +fn a_supplied_contradiction_cannot_be_ignored_as_unrequested_optional_metadata() { + let mut plan = plan(); + plan.expectations.push(expectation()); + let mut verified = VerifiedArtifacts::default(); + let runs = ["main", "control", "probe"].map(|id| receipt(&plan, id, &mut verified)); + let mut audit = audit(&plan, &mut verified); + audit.verdict = AuditVerdict::Contradicted; + let audits = [audit]; + let mut context = EvaluationContext::new(1020, &plan.subject, &verified); + context.audits = &audits; + assert!(!evaluate(&plan, &runs, &context).passed()); +} From 9a754a888f242e991e48173e0f8b3cbd0ab7cec1 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 3 Nov 2026 10:43:13 +0000 Subject: [PATCH 03/16] feat: package portable VisionCraft engineering skill and source migration --- docs/MIGRATION.md | 91 +++ docs/PROVENANCE.md | 78 +++ skills/visioncraft/SKILL.md | 121 ++++ skills/visioncraft/assets/activation.md | 55 ++ skills/visioncraft/assets/adr.md | 29 + skills/visioncraft/assets/expectation.md | 35 ++ skills/visioncraft/assets/legacy-paths.json | 264 +++++++++ skills/visioncraft/assets/provenance.json | 406 +++++++++++++ skills/visioncraft/assets/traceability.md | 26 + skills/visioncraft/assets/workshop.md | 18 + skills/visioncraft/references/architecture.md | 63 ++ skills/visioncraft/references/debugging.md | 84 +++ skills/visioncraft/references/deepsec.md | 77 +++ .../references/diagram-diagnosis.md | 73 +++ .../references/ecosystem-agentbox.md | 71 +++ skills/visioncraft/references/edd.md | 113 ++++ skills/visioncraft/references/evaluation.md | 74 +++ .../visioncraft/references/methodologies.md | 69 +++ skills/visioncraft/references/migration.md | 25 + .../visioncraft/references/quality-gates.md | 83 +++ .../visioncraft/references/review-evidence.md | 162 +++++ skills/visioncraft/references/roles.md | 60 ++ skills/visioncraft/references/rust/NOTICE.md | 53 ++ .../references/rust/lints/clippy.toml | 12 + .../references/rust/lints/lints.toml | 73 +++ skills/visioncraft/references/rust/port.md | 149 +++++ skills/visioncraft/references/rust/review.md | 181 ++++++ .../references/rust/sources/effective-rust.md | 196 ++++++ .../rust/sources/google-rust-style-guide.md | 208 +++++++ .../rust/sources/microsoft-rust-guidelines.md | 269 +++++++++ .../rust/sources/rust-api-guidelines.md | 214 +++++++ .../rust/sources/rust-design-patterns.md | 184 ++++++ .../visioncraft/references/rust/steering.md | 557 ++++++++++++++++++ skills/visioncraft/references/traceability.md | 73 +++ .../visioncraft/references/worked-examples.md | 162 +++++ 35 files changed, 4408 insertions(+) create mode 100644 docs/MIGRATION.md create mode 100644 docs/PROVENANCE.md create mode 100644 skills/visioncraft/SKILL.md create mode 100644 skills/visioncraft/assets/activation.md create mode 100644 skills/visioncraft/assets/adr.md create mode 100644 skills/visioncraft/assets/expectation.md create mode 100644 skills/visioncraft/assets/legacy-paths.json create mode 100644 skills/visioncraft/assets/provenance.json create mode 100644 skills/visioncraft/assets/traceability.md create mode 100644 skills/visioncraft/assets/workshop.md create mode 100644 skills/visioncraft/references/architecture.md create mode 100644 skills/visioncraft/references/debugging.md create mode 100644 skills/visioncraft/references/deepsec.md create mode 100644 skills/visioncraft/references/diagram-diagnosis.md create mode 100644 skills/visioncraft/references/ecosystem-agentbox.md create mode 100644 skills/visioncraft/references/edd.md create mode 100644 skills/visioncraft/references/evaluation.md create mode 100644 skills/visioncraft/references/methodologies.md create mode 100644 skills/visioncraft/references/migration.md create mode 100644 skills/visioncraft/references/quality-gates.md create mode 100644 skills/visioncraft/references/review-evidence.md create mode 100644 skills/visioncraft/references/roles.md create mode 100644 skills/visioncraft/references/rust/NOTICE.md create mode 100644 skills/visioncraft/references/rust/lints/clippy.toml create mode 100644 skills/visioncraft/references/rust/lints/lints.toml create mode 100644 skills/visioncraft/references/rust/port.md create mode 100644 skills/visioncraft/references/rust/review.md create mode 100644 skills/visioncraft/references/rust/sources/effective-rust.md create mode 100644 skills/visioncraft/references/rust/sources/google-rust-style-guide.md create mode 100644 skills/visioncraft/references/rust/sources/microsoft-rust-guidelines.md create mode 100644 skills/visioncraft/references/rust/sources/rust-api-guidelines.md create mode 100644 skills/visioncraft/references/rust/sources/rust-design-patterns.md create mode 100644 skills/visioncraft/references/rust/steering.md create mode 100644 skills/visioncraft/references/traceability.md create mode 100644 skills/visioncraft/references/worked-examples.md diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md new file mode 100644 index 0000000..b64e373 --- /dev/null +++ b/docs/MIGRATION.md @@ -0,0 +1,91 @@ +# Migration from build-with-quality + +This authorised cutover replaces the active build-with-quality system with one +canonical VisionCraft payload and executable. Once the new gates pass, migrate +all active callers and rebuild the consumer. Do not retain an old-name skill, +redirect, duplicate method tree or parallel wrapper implementation. Historical +documents keep their original claims and revisions with dated amendments where +needed. + +## Preserved method and changed boundaries + +VisionCraft retains EDD's seven-step loop and evidence categories, +feedback-loop debugging and static-oracle mode, diagram diagnosis, DDD/ADR/TDD, +BHIL-style traceability, all review-lesson families, five project examples and +the full Rust guidance/digests/lints. Responsibilities are logical roles unless +an actual host execution is recorded. Required unavailable evidence does not +become a pass through a weaker fallback. + +No Agentbox, model provider, memory service, fleet or paid review is required by +the portable entrypoint. Agentbox's policies and actual capabilities are an +optional documented integration. The removed npm classes and the old loaderless +YAML are retired interfaces, not hidden VisionCraft functionality. No empirical +uplift is inferred from this migration. + +## Complete 28-file map + +Source: Agentbox `a9125eaf006e2679f5b81444c3c06d0fb45b7481`, relative to +`skills/build-with-quality/`. Resource targets below are relative to the new +`skills/visioncraft/` root. The [machine-readable roster](../skills/visioncraft/assets/legacy-paths.json) +includes exact original blob IDs and SHA-256 values. A map row is an instruction +to migrate a caller, not an installed backward-compatibility alias. + +| Original path | New target or retirement | Preserved responsibility / action | +|---|---|---| +| `SKILL.md` | `SKILL.md` | Rewrite every active caller/registry/picker to visioncraft and remove the legacy entrypoint at hard cutover; no retained redirect. | +| `README.md` | `references/migration.md` | Historical removed npm API is documented as retired; actual CLI/library documentation belongs to the package README. | +| `BUILD-WITH-QUALITY-PROMPT.md` | `assets/activation.md` | Rewritten portable task brief preserves phases and explicit profile choices. | +| `DEBUGGING-PROTOCOL.md` | `references/debugging.md` | Feedback loop, blocked setup, static oracle and design interrogation; diagram diagnosis is separately linked. | +| `EDD-PROTOCOL.md` | `references/edd.md` | Seven steps, evidence categories, independence, freshness, workshops and stabilisation retained without host model defaults. | +| `USAGE-EXAMPLES.md` | `references/worked-examples.md` | All five project examples retained as explicit example contracts, not claimed execution. | +| `config/skill.yaml` | **retired** | No discovered runtime loader; retire this descriptive config instead of advertising inert policy. See references/architecture.md. | +| `scripts/deepsec-gate.sh` | **execution-migration** | Rewrite all callers to the installed VisionCraft Deepsec command and remove the old script; verify argument/exit/receipt contracts in adapter tests. | +| `scripts/deepsec-gate.test.mjs` | **execution-migration** | Migrate behavioural cases into the Rust/host conformance suites; remove the old wrapper test implementation. Source is not copied into this portable skill. | +| `references/agents.md` | `references/roles.md` | All 34 historical labels remain logical roles; coordination and unavailable ML labels do not become workers. | +| `references/architecture.md` | `references/architecture.md` | Portable boundaries and optional host capabilities replace unsupported learning, consensus and benchmark claims. | +| `references/bhil-traceability.md` | `references/traceability.md` | Requirement/decision/task/release lineage plus prompt/evaluation/guardrail concepts, independently worded. | +| `references/deepsec-security-gate.md` | `references/deepsec.md` | Protocol-level completion, exports, failure and scope guidance; host setup is in ecosystem-agentbox.md. | +| `references/methodologies.md` | `references/methodologies.md` | DDD/ADR/TDD and non-vacuous source verification retained; no assumed ADR plugin runtime. | +| `references/migration.md` | `references/migration.md` | Canonical successor and explicit retired surfaces. | +| `references/quality-gates-and-workflow.md` | `references/quality-gates.md` | Six check families and lifecycle retained with project-specific applicability and honest outcomes. | +| `references/review-evidence.md` | `references/review-evidence.md` | All audit lesson families rewritten around cause, consumed version, authority, effects, gate completion and delivery. | +| `references/rust/NOTICE.md` | `references/rust/NOTICE.md` | MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance. | +| `references/rust/steering.md` | `references/rust/steering.md` | MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance. | +| `references/rust/review.md` | `references/rust/review.md` | MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance. | +| `references/rust/port.md` | `references/rust/port.md` | MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance. | +| `references/rust/lints/clippy.toml` | `references/rust/lints/clippy.toml` | MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance. | +| `references/rust/lints/lints.toml` | `references/rust/lints/lints.toml` | MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance. | +| `references/rust/sources/effective-rust.md` | `references/rust/sources/effective-rust.md` | MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance. | +| `references/rust/sources/google-rust-style-guide.md` | `references/rust/sources/google-rust-style-guide.md` | MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance. | +| `references/rust/sources/microsoft-rust-guidelines.md` | `references/rust/sources/microsoft-rust-guidelines.md` | MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance. | +| `references/rust/sources/rust-api-guidelines.md` | `references/rust/sources/rust-api-guidelines.md` | MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance. | +| `references/rust/sources/rust-design-patterns.md` | `references/rust/sources/rust-design-patterns.md` | MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance. | + +## Consumer cutover contract + +1. Pin and install the complete released `skills/visioncraft/` tree. Check its + bytes against the immutable source, including Rust notices and referenced + assets; an entrypoint without its references is not the payload. +2. Rewrite both harness registries, discovery/routing sources, the Jev picker, + generated indexes, stack projection, preflight, agent instructions, neighbour + skills and active documentation. Regenerate associated fixtures from the + reviewed source change; changing a golden label is not measured routing uplift. +3. Rewrite every direct uppercase protocol/reference path through the map above. + Replace old Deepsec script invocations with the installed VisionCraft command + and test flags, environment precedence, exits, completion/export semantics + and receipt paths. Migrate meaningful tests; remove the old implementation. +4. Remove the old active skill and registration. Check the installed harness + reconciliation behaviour explicitly: deleting a manifest row must not leave + a stale discoverable personal skill directory. Keep historical audit evidence + pinned to the old version rather than mass-renaming its contents. +5. Check a generic no-Agentbox consumer as well as the host adapter. Verify the + released dependency/lockfile and source hash after removing local development + patches. Then rebuild and observe installed versions and a harmless end-to-end + check before claiming deployed activation. + +Do not create a second memory, finding or budget ledger during this cutover. +Sealmap remains the finding/disposition and model-family contract owner. Source +changes, publication, consumer adoption and runtime activation retain separate +receipts. The [Agentbox use case](../skills/visioncraft/references/ecosystem-agentbox.md) +provides the integration-specific boundary; [PROVENANCE.md](PROVENANCE.md) +records licensing and source treatment. diff --git a/docs/PROVENANCE.md b/docs/PROVENANCE.md new file mode 100644 index 0000000..8b06de7 --- /dev/null +++ b/docs/PROVENANCE.md @@ -0,0 +1,78 @@ +# Skill provenance and redistribution + +VisionCraft's portable method was written from the behavioural inventory of +Agentbox's build-with-quality skill. It preserves the engineering responsibilities +without copying the old executable wrapper, descriptive configuration or removed +TypeScript API into a differently licensed runtime. + +This migration examines Agentbox +`a9125eaf006e2679f5b81444c3c06d0fb45b7481`, under +`skills/build-with-quality/`. It contains the same 28 paths as the frozen +inventory at `4e1f4fff4e0f7827e8588c33bbf031c8420f52ad`; the later source updates +the Deepsec operating reference. Historical source remains recoverable in Git. + +## File-level records + +[The migration map](../skills/visioncraft/assets/legacy-paths.json) records all +28 original paths, their Git blob IDs, SHA-256 bytes, preserved responsibilities, +new resource or explicit retirement, and caller action. Its path set is checked +against the pinned Git tree. + +[The provenance manifest](../skills/visioncraft/assets/provenance.json) records +every file in the portable payload, its licence, treatment and relevant source +mapping. Newly authored guidance and migration data use the project's +`MIT OR Apache-2.0` terms. `docs/MIGRATION.md` and this file are newly written +under the same project terms. A file record describes the import history; it +does not certify legal status of unrelated upstream repositories. + +Agentbox's root licence and the old skill's MIT declarations are not treated as +a blanket permission to relicense its entire executable source. The portable +non-Rust prose is newly written around observable responsibilities and failure +contracts. Agentbox-specific integration implementation remains its own source +and licence. The Rust implementation is separately authored by the package +maintainers; it is not the old shell/Python wrapper copied into this payload. + +## BeautifulRust material + +The Rust subtree credits Morgan Linton's BeautifulRust at +`a9cdcfa94d1330c0d41c7f67764c5f7786fbb71d`. The complete inherited MIT notice, +copyright and upstream mapping remain in +[NOTICE.md](../skills/visioncraft/references/rust/NOTICE.md), followed by a clear +VisionCraft migration note. + +- Five source digests and both lint assets are byte-identical to the pinned + Agentbox import. Their source links and attributions remain intact. +- The three Rust method bodies retain the MIT language guidance. All thirteen + steering sections remain reachable. New portable scope text replaces the + estate-specific steering/port overlays, review intake, dead-path guidance and + affected links. The old rule that an unavailable reproduction should be + rejected is corrected: unavailable evidence remains inconclusive. +- The provenance manifest distinguishes retained bytes from modified bodies + and records the pinned BeautifulRust source paths. This is an import mapping, + not a claim that the underlying books or upstream guides were independently + re-audited during this migration. +- Lints are opt-in assets. They do not change a consuming repository until + deliberately installed and tested with its actual toolchain/MSRV. + +## Method lineage without an invented licence grant + +Legacy documentation associated feedback-loop debugging with Matt Pocock's +diagnose method, traceability with BHIL, and some knowledge/coordination ideas +with KHIVE/RuvNet. Those acknowledgements did not supply pinned grants for +copying their prose. VisionCraft's corresponding explanations, tables and +worksheets are newly written descriptions of engineering practice; no source +text from those external projects is vendored here. The source inventory retains +the historical attributions for readers investigating that lineage. + +Retained Rust digests carry their own underlying-source acknowledgements. +Do not remove those notices or treat future upstream additions as covered by +this import record without checking them. + +## Evidence limits + +Structural checks, licence manifests and path coverage do not establish a +measured task-success improvement. Public examples are illustrative contracts +unless accompanied by executed receipts. Independent forward testing and a +held-out comparison are separate evaluations, reported with their actual +subjects and observations. No unsupported speed, token-saving, prediction or +consensus claims are carried forward from the old descriptive configuration. diff --git a/skills/visioncraft/SKILL.md b/skills/visioncraft/SKILL.md new file mode 100644 index 0000000..3a0146b --- /dev/null +++ b/skills/visioncraft/SKILL.md @@ -0,0 +1,121 @@ +--- +name: visioncraft +description: Builds features with proportionate tests and evidence, diagnoses persistent bugs, and checks engineering designs and release gates. Use for expectation-driven development, difficult debugging, imported review findings, Rust changes, or a requested quality review. Simple edits and standalone prose changes do not need the full workflow. +license: MIT OR Apache-2.0 +metadata: + version: "0.1.0" + category: "engineering-quality" +--- + +# VisionCraft + +Make the requested change, establish what the evidence supports, and leave a +result another person can inspect. Scale the method to the change: a small +repair may need one regression and its control; a shared protocol change may +need expectations, consumer fixtures, an independent review and release checks. + +VisionCraft supplies a method and a separate executable library/CLI. Reading +this skill does not start tools, install an agent fleet, change project policy, +or authorise external calls. Use the repository's actual tool and API versions. +Installed command help and package documentation describe the shipped +command surface. + +## Choose the useful depth + +| Situation | Read next | +|---|---| +| Behaviour is unclear or spans several requirements | [EDD](references/edd.md), [expectation template](assets/expectation.md) | +| A bug resists a straightforward fix | [Debugging](references/debugging.md) | +| No runtime exists in the task environment | [Static-oracle mode](references/debugging.md#static-oracle-mode) | +| Several writers, validators or routes may disagree | [Diagram diagnosis](references/diagram-diagnosis.md) | +| Architecture or domain boundaries need a decision | [DDD, ADR and TDD](references/methodologies.md) | +| Specifications, prompts and delivery need lineage | [Traceability](references/traceability.md) | +| An audit or reviewer supplied findings | [Review evidence](references/review-evidence.md) | +| A merge/release needs applicable checks | [Quality gates](references/quality-gates.md), [Deepsec adapter](references/deepsec.md) | +| Rust is being written, reviewed or ported | [Steering](references/rust/steering.md), [review](references/rust/review.md), [port](references/rust/port.md) | +| Several participants are actually available | [Logical roles](references/roles.md) | +| A concrete project example helps scope the work | [Five worked examples](references/worked-examples.md) | + +Load only the resources needed for the task. The full +[activation template](assets/activation.md) is useful for a larger assignment; +it is not required ceremony for every edit. + +## Start from the actual task + +1. Read the request, repository instructions, changed files and relevant callers. + Preserve work owned by other people. Retrieve existing project decisions + through the host's approved knowledge tools when available. +2. Name the intended behaviour, supported configuration and important failure + case. Search existing contracts before asking for missing information. Ask + only when an unresolved choice materially changes the work; existing session + authorisation remains valid. +3. Choose a check that can distinguish the defect from failed setup. Keep a + supported positive control. If execution is temporarily blocked, retain that + result and continue independent investigation without claiming a pass. +4. Declare the smallest adequate scope: files, consumer version, required checks, + output location, and review policy. Security review and paid model calls + follow the project's cadence and authorisation, not a per-edit default here. + +## Implement and establish evidence + +- Formulate coherent expectations before substantial implementation; use TDD + to turn important examples into executable regressions. Prefer the existing + implementation owner and shared contract fixtures over another copy. +- Run the failing case and read its first failed assertion. Fix the cause, + rerun that case and its valid control, then run the relevant repository gates. + Stop broadening tests once the applicable checks pass unless a new concern + justifies further work. +- Preserve exact commands, raw outputs, time, full revision, relevant dirty or + untracked bytes, features and consumed dependency versions. Distinguish the + intended input set from what a reviewer actually inspected. +- For risk that requires independent review, identify the actual producer and + auditor executions and their model families. Different provider names or + role labels are insufficient. A same-family second opinion is useful but + does not satisfy a required cross-family check. +- After two unsuccessful fixes to the same failure, reassess the hypothesis + and seek another view if available. Do not keep editing the same symptom. +- Keep required unavailable, skipped, timed-out or inconclusive checks visible. + They cannot become a successful gate by omitting their rows. + +## Review findings and delivery + +Treat imported findings as hypotheses. Preserve the original export; record +confirmation, rejection, accepted risk or inconclusive evidence beside it. +Failure to reproduce because setup is unavailable is not rejection. A clean +review is not proof of correctness. + +Use the existing issue/register system. Where a structured adjacent receipt is +useful, Sealmap owns that contract: + +```sh +sealmap review init findings.json --out receipts.json +sealmap review check receipts.json --json +sealmap review summary receipts.json +``` + +These commands require an installed compatible Sealmap. Add real observations +before claiming resolution. Its CLI checks referenced bytes and structure; +the library's structural validator does not read those files. Neither decides +whether an observation proves the claim. See [review evidence](references/review-evidence.md). + +Before completion, inspect the full diff and any required independent review. +Report changed behaviour, checks actually run, remaining limits, and the next +acceptance condition. Keep source, tested, merged, published, adopted and +deployed evidence separate. Archive useful raw evidence before removing owned +temporary worktrees or caches. A reduced scope changes the denominator; it +does not complete the removed work. + +## Optional integration and evaluation + +[Architecture and boundaries](references/architecture.md) explains how a CLI, +repository, CI runner and reviewer can compose the method. The +[Agentbox use case](references/ecosystem-agentbox.md) describes one host's +memory, discovery, security and compatibility policies without making them +requirements for other users. + +[Evaluation](references/evaluation.md) separates structural validation, public +acceptance examples and independent forward tests from measured held-out +improvement. No performance or success-rate uplift is implied by this rewrite. +Third-party Rust material retains its [full notice](references/rust/NOTICE.md). +The [migration guide](references/migration.md), [source path map](assets/legacy-paths.json) +and [file provenance](assets/provenance.json) identify retained and retired resources. diff --git a/skills/visioncraft/assets/activation.md b/skills/visioncraft/assets/activation.md new file mode 100644 index 0000000..273e650 --- /dev/null +++ b/skills/visioncraft/assets/activation.md @@ -0,0 +1,55 @@ +# Task brief for VisionCraft + +Copy the relevant sections into an issue or request and replace the example +values with the actual task. This is a human-readable brief, not executable +configuration. Omit sections that do not help the assignment. + +## Outcome and boundary + +- Project, repository and supported stack: +- Requested behaviour and the user journey it serves: +- Current observed failure or missing capability: +- In scope and explicitly excluded adjacent work: +- Existing instruction, requirement, issue and decision references: +- Work owned by other people and isolation constraints: + +## Expectations + +Describe each coherent behaviour, boundaries, errors and a counterexample. +Mark regression-critical expectations. Use `assets/expectation.md` when a +separate record helps; an existing issue/test description is sufficient for a +small repair. + +## Method and checks + +Choose the useful entry mode: ordinary implementation, EDD, difficult debugging, +static-oracle reasoning, diagram diagnosis, review intake or Rust port. +Identify the supported positive control and the failing case. List required +checks, applicable feature/target matrix and the evidence each should establish. +Record optional checks and their limits rather than treating omissions as pass. + +## Participants and authority + +Identify the implementer, evidence producer, optional advisor and required +reviewer by actual capabilities. State any independence requirement. Sequential +work is valid when no delegation is needed. State existing authorisation for +external reviews, paid calls, deployment or other effects; do not infer it from +the skill name. No model or provider is required by this template. + +## Evidence and completion + +Choose the existing issue/register and private evidence location. Capture full +revisions, relevant dirty/untracked inputs, actual commands and output, time, +configuration, consumed dependencies and observed state. Keep source/test/ +merge/publication/adoption/deployment separately evidenced. Name the final +acceptance condition and the bounded stopping point. + +## Profile choices + +- Prototype: keep supported-path correctness checks; explicitly state what + production criteria are outside scope. +- Maintenance: focused regression/control plus applicable repository gates. +- Critical shared contract: expectations, consumer parity, required independent + review, recovery/migration and release/consumer evidence as applicable. + +Do not fill missing evidence with a profile label or a generic percentage. diff --git a/skills/visioncraft/assets/adr.md b/skills/visioncraft/assets/adr.md new file mode 100644 index 0000000..69ab608 --- /dev/null +++ b/skills/visioncraft/assets/adr.md @@ -0,0 +1,29 @@ +# Architecture decision worksheet + +Use the repository's ADR format if present. This worksheet is documentation, +not an automatic ratification or staleness mechanism. + +## Identity and status + +Record the decision ID, title, date, owner/authority and actual status. New +proposals remain proposed until accepted under the project's process. Link +dependencies, amendments and superseded decisions. + +## Context and alternatives + +Describe the behaviour or constraint requiring a choice, known observations, +credible alternatives and the tradeoff that matters. Separate facts from +assumptions and identify uncertainty that could change the decision. + +## Decision and consequences + +State the chosen boundary, consumer responsibilities, expected costs, risks and +reversal/migration path. Explain how the choice will be tested or reconsidered. + +## Source verification + +For implemented claims, record the inspected full commit and nonempty governed +paths plus relevant dependencies/configuration. Link actual checks. For an +unimplemented proposal, leave implementation verification explicitly absent. +Commit the code before stamping its revision. A later changed path creates a +review obligation, not automatic proof that this decision is wrong. diff --git a/skills/visioncraft/assets/expectation.md b/skills/visioncraft/assets/expectation.md new file mode 100644 index 0000000..ac89845 --- /dev/null +++ b/skills/visioncraft/assets/expectation.md @@ -0,0 +1,35 @@ +# Expectation worksheet + +This is a documentation template, not a VisionCraft JSON schema. Reuse existing +project IDs and statuses. An author status records intent; it does not establish +that checks ran. + +| Field | Record | +|---|---| +| ID and parent requirement | Stable existing reference | +| Related decisions/work items | Resolvable IDs, paths or URLs | +| Behaviour | One coherent externally observable claim | +| Priority and regression importance | Why its consequences justify the selected checks | +| Evidence category | Executable, partially verifiable or attributed manual observation | +| Author/status | Actual author and project status | +| In scope | Boundaries, order, errors and supported cases | +| Out of scope | Adjacent work excluded intentionally | +| Counterexample | An input/effect that would falsify the claim | +| Evidence references | Exact subject, commands/observations and raw artefacts | +| Required audit | Real reviewer/probe and independence evidence, if applicable | +| Stabiliser | Named meaningful check plus successful execution, when required | +| Freshness | Relevant inputs, ancestry/age policy and unresolved gaps | + +## Filled design example: cart operation order + +This example contract computes subtotal, applies one discount, then taxes the +discounted amount. It defines rounding at each currency boundary. An empty cart +returns zero. Multiple-code stacking and currency conversion are separately +specified. Counterexamples include taxing the original subtotal, losing cents +through binary floating-point conversion, and altering a cart after rejecting a +second code. + +For a subtotal of 45.00, a 10% discount and 8% tax, the expected intermediate +values are 4.50 discount, 40.50 taxable and 3.24 tax, yielding 43.74. These are +expected values for a future executed check, not a fabricated API response. +Its valid control, empty-cart case and rounding boundary need real receipts. diff --git a/skills/visioncraft/assets/legacy-paths.json b/skills/visioncraft/assets/legacy-paths.json new file mode 100644 index 0000000..f3b1be1 --- /dev/null +++ b/skills/visioncraft/assets/legacy-paths.json @@ -0,0 +1,264 @@ +{ + "version": 1, + "cutover": "hard; migrate active callers then remove old entrypoints and implementation", + "source": { + "repository": "https://github.com/DreamLab-AI/agentbox", + "revision": "a9125eaf006e2679f5b81444c3c06d0fb45b7481", + "root": "skills/build-with-quality/" + }, + "canonical_root": "skills/visioncraft/", + "mappings": [ + { + "legacy_path": "SKILL.md", + "kind": "entrypoint", + "target": "SKILL.md", + "source_sha256": "4bfc807b6c5e518b5dc2847186f0503fb001c7061cf6a60851bbb4916afe6a53", + "source_git_blob": "19f9fd9433ccd04e7329a84e6dc8d41d28e3bb12", + "preserved_capability": "Entry workflow, when/when-not, model roles, gates", + "migration": "Rewrite every active caller/registry/picker to visioncraft and remove the legacy entrypoint at hard cutover; no retained redirect." + }, + { + "legacy_path": "README.md", + "kind": "resource", + "target": "references/migration.md", + "source_sha256": "b60e2f4e52d0f285cad7171d08c2a55cc56fa4b7d37f0f9fe5fd7432d3373bf2", + "source_git_blob": "55b664dea2d4e16828e2c38b4a2abbc22d5adc2c", + "preserved_capability": "Overview, install, examples, API, targets, migration", + "migration": "Historical removed npm API is documented as retired; actual CLI/library documentation belongs to the package README." + }, + { + "legacy_path": "BUILD-WITH-QUALITY-PROMPT.md", + "kind": "resource", + "target": "assets/activation.md", + "source_sha256": "7f7a0ad86f9b88159d372cb44a78da4a6091e972ca229761ff03ee0e434eb32f", + "source_git_blob": "6c8ba1ee720168c2953c6931503cb6c641e877b6", + "preserved_capability": "Full activation prompt, six gates, profiles, topology, degraded modes", + "migration": "Rewritten portable task brief preserves phases and explicit profile choices." + }, + { + "legacy_path": "DEBUGGING-PROTOCOL.md", + "kind": "resource", + "target": "references/debugging.md", + "source_sha256": "e6f4997dd2c895d25e5754e3743f9ae8f88ae57a32289364b8f4602028fb5c7d", + "source_git_blob": "00ebc6fb36a5b06f3e627bb6c9d2a27a2225aa60", + "preserved_capability": "Feedback loop, static oracle, ranked hypotheses, diagram diagnosis, design interrogation", + "migration": "Feedback loop, blocked setup, static oracle and design interrogation; diagram diagnosis is separately linked." + }, + { + "legacy_path": "EDD-PROTOCOL.md", + "kind": "resource", + "target": "references/edd.md", + "source_sha256": "f403ca0cfbe4ec40962b3912050850a8ccd7daa9bb008f311501ab6ea17dd318", + "source_git_blob": "c52d56910f8e34532656f3ff949a8c85e52d5c57", + "preserved_capability": "Seven-step EDD, expectations, receipts, independence, ageing, stabilisation, workshops", + "migration": "Seven steps, evidence categories, independence, freshness, workshops and stabilisation retained without host model defaults." + }, + { + "legacy_path": "USAGE-EXAMPLES.md", + "kind": "resource", + "target": "references/worked-examples.md", + "source_sha256": "d46150856d4949bebc6bbaa89aad718979a5777715141d0fc43269440802d0e6", + "source_git_blob": "9b131b7169efa09a9e516d686d311d7232689935", + "preserved_capability": "Five complete project examples and priority/quality variations", + "migration": "All five project examples retained as explicit example contracts, not claimed execution." + }, + { + "legacy_path": "config/skill.yaml", + "kind": "retired", + "target": null, + "source_sha256": "2664eba6c09e2a644d52e79327b225898a678e25f8486d1a85c630558a6f00eb", + "source_git_blob": "0c7d62ffaf912216e2a72ead067e38ab0c78ecb1", + "preserved_capability": "Configuration-shaped capability/domain/gate/model/workflow catalogue", + "migration": "No discovered runtime loader; retire this descriptive config instead of advertising inert policy. See references/architecture.md." + }, + { + "legacy_path": "scripts/deepsec-gate.sh", + "kind": "execution-migration", + "target": null, + "source_sha256": "bb0495c9fcfe3e24fd6229483f67bce7d845938bc6e4098a425c7d0301f002a7", + "source_git_blob": "6d68196732aee6a364b09970c3ef7029b73b9dad", + "preserved_capability": "Policy/route/preflight, bounded process, fresh receipts, export/threshold parser", + "migration": "Rewrite all callers to the installed VisionCraft Deepsec command and remove the old script; verify argument/exit/receipt contracts in adapter tests." + }, + { + "legacy_path": "scripts/deepsec-gate.test.mjs", + "kind": "execution-migration", + "target": null, + "source_sha256": "4e365e98698e5fa51d0e570ffb8f8f28d877f50e575a7ca84ee7f4286aadcfa4", + "source_git_blob": "9247cb0f2a72c918d6122821ef8f1f0b253418b6", + "preserved_capability": "Offline provider double and process/receipt/error controls", + "migration": "Migrate behavioural cases into the Rust/host conformance suites; remove the old wrapper test implementation. Source is not copied into this portable skill." + }, + { + "legacy_path": "references/agents.md", + "kind": "resource", + "target": "references/roles.md", + "source_sha256": "4679e71e7d2089423336e1941b97445f7f0b281323b2ed0320ede326caddeba7", + "source_git_blob": "c45dc816663fef0c57fc30f945b8996565774c32", + "preserved_capability": "34 logical roles and actual registered harness mapping", + "migration": "All 34 historical labels remain logical roles; coordination and unavailable ML labels do not become workers." + }, + { + "legacy_path": "references/architecture.md", + "kind": "resource", + "target": "references/architecture.md", + "source_sha256": "241516a8b38a7a05566f344f024a442f9686c9b13913926bec3d3029041f9766", + "source_git_blob": "d1727df1e8f3fd50cadf5a01cf9ee1319021529c", + "preserved_capability": "Learning/memory/roles/execution, proposed enhancements, targets", + "migration": "Portable boundaries and optional host capabilities replace unsupported learning, consensus and benchmark claims." + }, + { + "legacy_path": "references/bhil-traceability.md", + "kind": "resource", + "target": "references/traceability.md", + "source_sha256": "e67f480f009e53295faee68b0fc9a7ff55182591485529722f1873aeea2b117f", + "source_git_blob": "4efdae74bb0082aad7741ab03847942ad4ac970e", + "preserved_capability": "PRD/SPEC/ADR/TASK graph, prompt versions, eval/guardrail templates", + "migration": "Requirement/decision/task/release lineage plus prompt/evaluation/guardrail concepts, independently worded." + }, + { + "legacy_path": "references/deepsec-security-gate.md", + "kind": "resource", + "target": "references/deepsec.md", + "source_sha256": "aa5c0c0ff267583260b89815766dde090a38f10523c2518558ceffa7b2794d16", + "source_git_blob": "8fffe035e0dc4e5df128da84becf0316a961cd6b", + "preserved_capability": "Actual gate operating contract, receipts, model routes, limits", + "migration": "Protocol-level completion, exports, failure and scope guidance; host setup is in ecosystem-agentbox.md." + }, + { + "legacy_path": "references/methodologies.md", + "kind": "resource", + "target": "references/methodologies.md", + "source_sha256": "f06d08cd4e69d40739403a705287333f28800f126009bdff7334f72ebb2479d0", + "source_git_blob": "25482c5ec763e91899a46741df2af9fc9f711cce", + "preserved_capability": "DDD/ADR/TDD, ADR staleness, optional Ruflo graph integration", + "migration": "DDD/ADR/TDD and non-vacuous source verification retained; no assumed ADR plugin runtime." + }, + { + "legacy_path": "references/migration.md", + "kind": "resource", + "target": "references/migration.md", + "source_sha256": "d1d74836a2aed309f58a11a435d1239433680159adb9bebf490274c161496f9d", + "source_git_blob": "290de4fdc172bfa1855d1824eb7d84c0ed7b2b48", + "preserved_capability": "Superseded skills and old invocation migrations", + "migration": "Canonical successor and explicit retired surfaces." + }, + { + "legacy_path": "references/quality-gates-and-workflow.md", + "kind": "resource", + "target": "references/quality-gates.md", + "source_sha256": "6f875f71a4bd62259c0c9608ef20b6ff1eb87931f9d016559dd90b05f7ec55ec", + "source_git_blob": "3aebeb122e7f90c5646ef2293ff86cd6599e8c92", + "preserved_capability": "Gate catalogue, findings intake, Sealmap receipts, Rust lens, advisor and phase flow", + "migration": "Six check families and lifecycle retained with project-specific applicability and honest outcomes." + }, + { + "legacy_path": "references/review-evidence.md", + "kind": "resource", + "target": "references/review-evidence.md", + "source_sha256": "d88fa12e3a91df6dba9975c6753e1594ddaf0a95e8f124163efbb6a3909c136d", + "source_git_blob": "4e3c4991f11faacd9defe1500893c617538891ab", + "preserved_capability": "Estate lessons: cause/version/effects, consolidation, gate semantics, delivery, release", + "migration": "All audit lesson families rewritten around cause, consumed version, authority, effects, gate completion and delivery." + }, + { + "legacy_path": "references/rust/NOTICE.md", + "kind": "resource", + "target": "references/rust/NOTICE.md", + "source_sha256": "c206613705f463853e862d7d966c30abc9df73f46ece83c486a2ae5c0d8f4ef2", + "source_git_blob": "73afec5870db4463c1964b0ea06da1dde321ad01", + "preserved_capability": "Vendored source pin, file coverage and complete MIT notice", + "migration": "MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance." + }, + { + "legacy_path": "references/rust/steering.md", + "kind": "resource", + "target": "references/rust/steering.md", + "source_sha256": "d3bb15d912ff61d78482d9f776f68368d5299f09166518bd1c6c6be8f4368ced", + "source_git_blob": "b9138f355a09234b1bc3a67af7e8f225926a6ece", + "preserved_capability": "Rust ownership/API/errors/async/unsafe/docs/tests/performance plus estate overlay", + "migration": "MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance." + }, + { + "legacy_path": "references/rust/review.md", + "kind": "resource", + "target": "references/rust/review.md", + "source_sha256": "8803404fbe00f2d6bdaa8c00555a2b37a4ad8f5570157bae94af8c7d5dfec29f", + "source_git_blob": "f7239c2a5adb5335be5423b921d31be07d934ce7", + "preserved_capability": "Risk-ordered Rust review and report format, lint/profile handoff", + "migration": "MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance." + }, + { + "legacy_path": "references/rust/port.md", + "kind": "resource", + "target": "references/rust/port.md", + "source_sha256": "33bd11deee4e0baf3c34a0059c48267684763631770847004c5dbd3a8362b1fd", + "source_git_blob": "ae04924c8b64b2289501343e169f23be80550b91", + "preserved_capability": "Whether to port, preserve behaviour/tests, per-language semantics, proportionality", + "migration": "MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance." + }, + { + "legacy_path": "references/rust/lints/clippy.toml", + "kind": "resource", + "target": "references/rust/lints/clippy.toml", + "source_sha256": "012446990fbaa1b4705319c7cf95ed59ffbd14ac7ca9ec4b907f27a0ead82c42", + "source_git_blob": "6365ddc2d8a444665f434fda23bfaaf8fbde6952", + "preserved_capability": "Clippy bool parameter and test allowances", + "migration": "MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance." + }, + { + "legacy_path": "references/rust/lints/lints.toml", + "kind": "resource", + "target": "references/rust/lints/lints.toml", + "source_sha256": "4dbf3367ff178738f248543e9ae298ad57c8de3fb797823e756b5edf3f7f9588", + "source_git_blob": "17047b82672ec487e0e32f97a00cc1ff9d89f52e", + "preserved_capability": "Cargo lint table with public API/unsafe/docs/error/cast policies", + "migration": "MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance." + }, + { + "legacy_path": "references/rust/sources/effective-rust.md", + "kind": "resource", + "target": "references/rust/sources/effective-rust.md", + "source_sha256": "c0fe4ea29d2601224ac68b307d8c6137dd932b2565c141c1527c88ba1c5d5415", + "source_git_blob": "2990d3efea1912e6a3aa893d8484b244f9e12c3d", + "preserved_capability": "Effective Rust digest,35 items", + "migration": "MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance." + }, + { + "legacy_path": "references/rust/sources/google-rust-style-guide.md", + "kind": "resource", + "target": "references/rust/sources/google-rust-style-guide.md", + "source_sha256": "cfe61cd554c9dc32b412bb22dec7bd58e9eb4b3931db79124a61b8c2f573542c", + "source_git_blob": "e408370dd7d3e721710273a40f672c147cc69c61", + "preserved_capability": "Google Rust style digest", + "migration": "MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance." + }, + { + "legacy_path": "references/rust/sources/microsoft-rust-guidelines.md", + "kind": "resource", + "target": "references/rust/sources/microsoft-rust-guidelines.md", + "source_sha256": "648cfee06cea304e3d9c525e6de9047c296ce353e156a8117111094418ccc4b8", + "source_git_blob": "d4ecd16408d49a0dd06f25c56ca075ce5515a731", + "preserved_capability": "Microsoft pragmatic Rust digest, including AI provenance guidance", + "migration": "MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance." + }, + { + "legacy_path": "references/rust/sources/rust-api-guidelines.md", + "kind": "resource", + "target": "references/rust/sources/rust-api-guidelines.md", + "source_sha256": "392a94ed5151a7eeaf6f0d0f0cbd29904fa41ae4c4ae5ae98d79e7da3ba2a8af", + "source_git_blob": "72c927784a610c999e390d378dd036b35d335b24", + "preserved_capability": "Official Rust API guidelines digest", + "migration": "MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance." + }, + { + "legacy_path": "references/rust/sources/rust-design-patterns.md", + "kind": "resource", + "target": "references/rust/sources/rust-design-patterns.md", + "source_sha256": "3102f45153ac7c75179ee43b12d143b33e4aaba9b2209c454dd4f0542cae7ae7", + "source_git_blob": "e92dfa31aa584dc0bfd76525b6a6f0edf58bc200", + "preserved_capability": "Rust idioms/patterns/anti-patterns/functional digest", + "migration": "MIT BeautifulRust resource retained; estate overlays replaced where noted in provenance." + } + ] +} diff --git a/skills/visioncraft/assets/provenance.json b/skills/visioncraft/assets/provenance.json new file mode 100644 index 0000000..e3b1298 --- /dev/null +++ b/skills/visioncraft/assets/provenance.json @@ -0,0 +1,406 @@ +{ + "version": 1, + "source_inventory": { + "repository": "https://github.com/DreamLab-AI/agentbox", + "revision": "a9125eaf006e2679f5b81444c3c06d0fb45b7481", + "root": "skills/build-with-quality/" + }, + "files": [ + { + "path": "SKILL.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [ + "SKILL.md" + ] + }, + { + "path": "assets/activation.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [ + "BUILD-WITH-QUALITY-PROMPT.md" + ] + }, + { + "path": "assets/adr.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [] + }, + { + "path": "assets/expectation.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [] + }, + { + "path": "assets/legacy-paths.json", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [] + }, + { + "path": "assets/traceability.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [] + }, + { + "path": "assets/workshop.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [] + }, + { + "path": "references/architecture.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [ + "references/architecture.md" + ] + }, + { + "path": "references/debugging.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [ + "DEBUGGING-PROTOCOL.md" + ] + }, + { + "path": "references/deepsec.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [ + "references/deepsec-security-gate.md" + ] + }, + { + "path": "references/diagram-diagnosis.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [] + }, + { + "path": "references/ecosystem-agentbox.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [] + }, + { + "path": "references/edd.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [ + "EDD-PROTOCOL.md" + ] + }, + { + "path": "references/evaluation.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [] + }, + { + "path": "references/methodologies.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [ + "references/methodologies.md" + ] + }, + { + "path": "references/migration.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [ + "README.md", + "references/migration.md" + ] + }, + { + "path": "references/quality-gates.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [ + "references/quality-gates-and-workflow.md" + ] + }, + { + "path": "references/review-evidence.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [ + "references/review-evidence.md" + ] + }, + { + "path": "references/roles.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [ + "references/agents.md" + ] + }, + { + "path": "references/rust/NOTICE.md", + "licence": "MIT; VisionCraft additions MIT OR Apache-2.0", + "treatment": "MIT body retained; independently written portable overlay, links or migration notice replaces estate wording", + "behavioural_sources": [ + "references/rust/NOTICE.md" + ], + "upstream": { + "repository": "https://github.com/morganlinton/BeautifulRust", + "revision": "a9cdcfa94d1330c0d41c7f67764c5f7786fbb71d", + "paths": [ + "LICENSE" + ] + }, + "source_import": { + "repository": "https://github.com/DreamLab-AI/agentbox", + "revision": "a9125eaf006e2679f5b81444c3c06d0fb45b7481", + "path": "skills/build-with-quality/references/rust/NOTICE.md", + "sha256": "c206613705f463853e862d7d966c30abc9df73f46ece83c486a2ae5c0d8f4ef2" + } + }, + { + "path": "references/rust/lints/clippy.toml", + "licence": "MIT", + "treatment": "byte-for-byte retained import", + "behavioural_sources": [ + "references/rust/lints/clippy.toml" + ], + "upstream": { + "repository": "https://github.com/morganlinton/BeautifulRust", + "revision": "a9cdcfa94d1330c0d41c7f67764c5f7786fbb71d", + "paths": [ + "lints/clippy.toml" + ] + }, + "source_import": { + "repository": "https://github.com/DreamLab-AI/agentbox", + "revision": "a9125eaf006e2679f5b81444c3c06d0fb45b7481", + "path": "skills/build-with-quality/references/rust/lints/clippy.toml", + "sha256": "012446990fbaa1b4705319c7cf95ed59ffbd14ac7ca9ec4b907f27a0ead82c42" + } + }, + { + "path": "references/rust/lints/lints.toml", + "licence": "MIT", + "treatment": "byte-for-byte retained import", + "behavioural_sources": [ + "references/rust/lints/lints.toml" + ], + "upstream": { + "repository": "https://github.com/morganlinton/BeautifulRust", + "revision": "a9cdcfa94d1330c0d41c7f67764c5f7786fbb71d", + "paths": [ + "lints/lints.toml" + ] + }, + "source_import": { + "repository": "https://github.com/DreamLab-AI/agentbox", + "revision": "a9125eaf006e2679f5b81444c3c06d0fb45b7481", + "path": "skills/build-with-quality/references/rust/lints/lints.toml", + "sha256": "4dbf3367ff178738f248543e9ae298ad57c8de3fb797823e756b5edf3f7f9588" + } + }, + { + "path": "references/rust/port.md", + "licence": "MIT; VisionCraft additions MIT OR Apache-2.0", + "treatment": "MIT body retained; independently written portable overlay, links or migration notice replaces estate wording", + "behavioural_sources": [ + "references/rust/port.md" + ], + "upstream": { + "repository": "https://github.com/morganlinton/BeautifulRust", + "revision": "a9cdcfa94d1330c0d41c7f67764c5f7786fbb71d", + "paths": [ + "skills/rust-port/SKILL.md" + ] + }, + "source_import": { + "repository": "https://github.com/DreamLab-AI/agentbox", + "revision": "a9125eaf006e2679f5b81444c3c06d0fb45b7481", + "path": "skills/build-with-quality/references/rust/port.md", + "sha256": "33bd11deee4e0baf3c34a0059c48267684763631770847004c5dbd3a8362b1fd" + } + }, + { + "path": "references/rust/review.md", + "licence": "MIT; VisionCraft additions MIT OR Apache-2.0", + "treatment": "MIT body retained; independently written portable overlay, links or migration notice replaces estate wording", + "behavioural_sources": [ + "references/rust/review.md" + ], + "upstream": { + "repository": "https://github.com/morganlinton/BeautifulRust", + "revision": "a9cdcfa94d1330c0d41c7f67764c5f7786fbb71d", + "paths": [ + "skills/rust-review/SKILL.md" + ] + }, + "source_import": { + "repository": "https://github.com/DreamLab-AI/agentbox", + "revision": "a9125eaf006e2679f5b81444c3c06d0fb45b7481", + "path": "skills/build-with-quality/references/rust/review.md", + "sha256": "8803404fbe00f2d6bdaa8c00555a2b37a4ad8f5570157bae94af8c7d5dfec29f" + } + }, + { + "path": "references/rust/sources/effective-rust.md", + "licence": "MIT", + "treatment": "byte-for-byte retained import", + "behavioural_sources": [ + "references/rust/sources/effective-rust.md" + ], + "upstream": { + "repository": "https://github.com/morganlinton/BeautifulRust", + "revision": "a9cdcfa94d1330c0d41c7f67764c5f7786fbb71d", + "paths": [ + "skills/rust-best-practices/references/effective-rust.md" + ] + }, + "source_import": { + "repository": "https://github.com/DreamLab-AI/agentbox", + "revision": "a9125eaf006e2679f5b81444c3c06d0fb45b7481", + "path": "skills/build-with-quality/references/rust/sources/effective-rust.md", + "sha256": "c0fe4ea29d2601224ac68b307d8c6137dd932b2565c141c1527c88ba1c5d5415" + } + }, + { + "path": "references/rust/sources/google-rust-style-guide.md", + "licence": "MIT", + "treatment": "byte-for-byte retained import", + "behavioural_sources": [ + "references/rust/sources/google-rust-style-guide.md" + ], + "upstream": { + "repository": "https://github.com/morganlinton/BeautifulRust", + "revision": "a9cdcfa94d1330c0d41c7f67764c5f7786fbb71d", + "paths": [ + "skills/rust-best-practices/references/google-rust-style-guide.md" + ] + }, + "source_import": { + "repository": "https://github.com/DreamLab-AI/agentbox", + "revision": "a9125eaf006e2679f5b81444c3c06d0fb45b7481", + "path": "skills/build-with-quality/references/rust/sources/google-rust-style-guide.md", + "sha256": "cfe61cd554c9dc32b412bb22dec7bd58e9eb4b3931db79124a61b8c2f573542c" + } + }, + { + "path": "references/rust/sources/microsoft-rust-guidelines.md", + "licence": "MIT", + "treatment": "byte-for-byte retained import", + "behavioural_sources": [ + "references/rust/sources/microsoft-rust-guidelines.md" + ], + "upstream": { + "repository": "https://github.com/morganlinton/BeautifulRust", + "revision": "a9cdcfa94d1330c0d41c7f67764c5f7786fbb71d", + "paths": [ + "skills/rust-best-practices/references/microsoft-rust-guidelines.md" + ] + }, + "source_import": { + "repository": "https://github.com/DreamLab-AI/agentbox", + "revision": "a9125eaf006e2679f5b81444c3c06d0fb45b7481", + "path": "skills/build-with-quality/references/rust/sources/microsoft-rust-guidelines.md", + "sha256": "648cfee06cea304e3d9c525e6de9047c296ce353e156a8117111094418ccc4b8" + } + }, + { + "path": "references/rust/sources/rust-api-guidelines.md", + "licence": "MIT", + "treatment": "byte-for-byte retained import", + "behavioural_sources": [ + "references/rust/sources/rust-api-guidelines.md" + ], + "upstream": { + "repository": "https://github.com/morganlinton/BeautifulRust", + "revision": "a9cdcfa94d1330c0d41c7f67764c5f7786fbb71d", + "paths": [ + "skills/rust-best-practices/references/rust-api-guidelines.md" + ] + }, + "source_import": { + "repository": "https://github.com/DreamLab-AI/agentbox", + "revision": "a9125eaf006e2679f5b81444c3c06d0fb45b7481", + "path": "skills/build-with-quality/references/rust/sources/rust-api-guidelines.md", + "sha256": "392a94ed5151a7eeaf6f0d0f0cbd29904fa41ae4c4ae5ae98d79e7da3ba2a8af" + } + }, + { + "path": "references/rust/sources/rust-design-patterns.md", + "licence": "MIT", + "treatment": "byte-for-byte retained import", + "behavioural_sources": [ + "references/rust/sources/rust-design-patterns.md" + ], + "upstream": { + "repository": "https://github.com/morganlinton/BeautifulRust", + "revision": "a9cdcfa94d1330c0d41c7f67764c5f7786fbb71d", + "paths": [ + "skills/rust-best-practices/references/rust-design-patterns.md" + ] + }, + "source_import": { + "repository": "https://github.com/DreamLab-AI/agentbox", + "revision": "a9125eaf006e2679f5b81444c3c06d0fb45b7481", + "path": "skills/build-with-quality/references/rust/sources/rust-design-patterns.md", + "sha256": "3102f45153ac7c75179ee43b12d143b33e4aaba9b2209c454dd4f0542cae7ae7" + } + }, + { + "path": "references/rust/steering.md", + "licence": "MIT; VisionCraft additions MIT OR Apache-2.0", + "treatment": "MIT body retained; independently written portable overlay, links or migration notice replaces estate wording", + "behavioural_sources": [ + "references/rust/steering.md" + ], + "upstream": { + "repository": "https://github.com/morganlinton/BeautifulRust", + "revision": "a9cdcfa94d1330c0d41c7f67764c5f7786fbb71d", + "paths": [ + "skills/rust-best-practices/SKILL.md" + ] + }, + "source_import": { + "repository": "https://github.com/DreamLab-AI/agentbox", + "revision": "a9125eaf006e2679f5b81444c3c06d0fb45b7481", + "path": "skills/build-with-quality/references/rust/steering.md", + "sha256": "d3bb15d912ff61d78482d9f776f68368d5299f09166518bd1c6c6be8f4368ced" + } + }, + { + "path": "references/traceability.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [ + "references/bhil-traceability.md" + ] + }, + { + "path": "references/worked-examples.md", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written guidance or migration data from the behavioural inventory", + "behavioural_sources": [ + "USAGE-EXAMPLES.md" + ] + }, + { + "path": "assets/provenance.json", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written file-level provenance manifest", + "behavioural_sources": [] + } + ], + "limitations": [ + "Agentbox source declarations mix root AGPL-3.0 and skill MIT; no wholesale relicensing of that source is claimed.", + "Non-Rust portable guidance was written anew from the behaviour inventory; legacy executable source and descriptive config were not copied.", + "Rust upstream mappings are the pinned import attribution, not a claim that upstream was fetched or re-audited during this migration.", + "This file records provenance, not empirical task-success improvement." + ] +} diff --git a/skills/visioncraft/assets/traceability.md b/skills/visioncraft/assets/traceability.md new file mode 100644 index 0000000..c3521e2 --- /dev/null +++ b/skills/visioncraft/assets/traceability.md @@ -0,0 +1,26 @@ +# Traceability worksheet + +Use this in the existing project record. It is a checklist of relationships, +not a new tracker or executable configuration file. + +| Link | Record and verify | +|---|---| +| Product requirement → specification | Intended user behaviour, boundaries and authority | +| Specification → expectation/decision | Precise examples, counterexamples and tradeoffs | +| Work item → implementation | Owning repository and exact source revision | +| Implementation → checks/review | Supported inputs, actual executions, artefacts and dispositions | +| Release → consumer | Immutable package/source hash, lockfile and consumer execution | +| Consumer → deployment | Running version and named observed acceptance | + +## Prompt or model change + +Record immutable prompt/model identity, output contract, linked decision, +evaluation revision, representative/adversarial cases, metrics and raw results. +Mark a breaking output-format change for its consumers. Distinguish deterministic +assertions from rubric judgements and use successful supported controls. + +## Guardrails + +Specify allowed input, rejection boundaries, output constraints, private data +handling, resource limits, fallback and escalation. Identify observation signals +and response owners. An unimplemented alert or evaluator remains a proposal. diff --git a/skills/visioncraft/assets/workshop.md b/skills/visioncraft/assets/workshop.md new file mode 100644 index 0000000..7800ea0 --- /dev/null +++ b/skills/visioncraft/assets/workshop.md @@ -0,0 +1,18 @@ +# Expectation workshop agenda + +Use a workshop for shared or consequential business rules, not by default for +every small edit. Reuse existing acceptance and decision records. + +1. Name the journey, authority and current domain vocabulary. +2. Have participants propose concrete success, boundary and failure examples. +3. Compare contradictions and exclusions before combining expectations. +4. Ask a participant other than the author to offer a falsifying input or effect. +5. Agree the evidence category, positive control, required independence and + regression-critical scenarios. +6. Record resolved choices, authority already granted and remaining questions. +7. Assign actual owners and a bounded next step; do not claim logical role + labels are executing workers. + +Retain significant rejected alternatives and why they were rejected. If a +subjective judgement or device observation remains, identify who can supply it +and what an acceptable observation would contain. diff --git a/skills/visioncraft/references/architecture.md b/skills/visioncraft/references/architecture.md new file mode 100644 index 0000000..f2bdd53 --- /dev/null +++ b/skills/visioncraft/references/architecture.md @@ -0,0 +1,63 @@ +# Portable method and execution boundaries + +VisionCraft has three distinct surfaces: this skill's engineering guidance, +the versioned library/CLI contracts, and host integrations. Guidance can name +useful checks that a project has not installed; an executable claim requires +the corresponding installed tool, configuration and retained result. + +## Ownership + +| Component | Owns | Does not establish | +|---|---|---| +| Skill | Task selection, evidence discipline, debugging and design methods | That any tool or worker ran | +| Quality plan | Declared checks, subject, expectations and policy | That the selected checks cover every relevant behaviour | +| Explicit runner | Bounded declared executions and retained output/receipts | A sandbox or proof that a scanner opened all intended inputs | +| Gate evaluator | Deterministic aggregation under a declared policy | Semantic correctness or human acceptance | +| Sealmap | Finding dispositions, delivery attestations and family declarations; CLI artefact checks | Independent verification of self-reported observations | +| Host/CI | Tool availability, credentials, network/spend policy, scheduling and deployments | Automatic satisfaction of required evidence | + +Use the package documentation for the actual released API. Do not treat a +Markdown template as runtime configuration or an API proposal as shipped code. +Historical `config/skill.yaml` had no discovered loader; it is retired as +an executable interface. This skill does not restore its ML, consensus or +orchestration claims. + +## Process and evidence + +Validation and reporting must not execute commands found in imported receipts. +Execution is explicit and scoped. An argv-based runner avoids implicit shell +expansion, but commands still have the caller's authority unless a separate +sandbox is actually applied. Bound duration and capture, retain incomplete +output on error, and stop/reap the whole owned process group on cancellation. + +Use fresh private output locations, exact input snapshots and real completion +signals. Record intended and observed scope separately. Concurrent source edits, +missing bytes, stale exports and capture failures cannot silently become a +successful current receipt. Managed-output path checks reduce accidental +redirection; they are not a general sandbox against hostile concurrent mutation. + +## Optional knowledge services + +A project may retain episodic attempts and durable lessons, use exact tags for +lookup, link entities/decisions, or combine lexical and semantic retrieval. +Those are useful host capabilities when implemented. Do not assume a vector +database, task DAG, memory-orientation endpoint, learning loop or background +consolidator exists because a reference describes one. + +Use the approved interface and schema; retain exact sources and scope with +reusable lessons. Absence of a knowledge service does not prevent ordinary +development. Do not introduce another findings store or install an engine as a +side effect of invoking this skill. Any prediction/retrieval improvement needs +its own dataset, baseline, metric and measured result. + +## Policy and degraded capability + +Project/session policy controls applicable checks, tools, review independence, +cost and external effects. A simpler environment can still use expectations, +local tests and source review. Missing required capability is reported as +unavailable/incomplete; it is not silently replaced by a weaker check with the +same green label. Optional capability can be omitted with its scope stated. + +The [Agentbox reference](ecosystem-agentbox.md) gives one concrete adapter case. +Other hosts can use their own CI, model providers, knowledge tools and issue +systems while consuming the same portable contracts. diff --git a/skills/visioncraft/references/debugging.md b/skills/visioncraft/references/debugging.md new file mode 100644 index 0000000..8c0cc79 --- /dev/null +++ b/skills/visioncraft/references/debugging.md @@ -0,0 +1,84 @@ +# Debugging from an observable failure + +Start by finding a signal that distinguishes the reported defect from a healthy +case. Optimise it for speed, specificity and reproducibility before changing +several implementation paths. The object is to explain the failure, not merely +make an assertion green. + +## Obtain a feedback loop + +Use the first suitable seam: a unit/integration/end-to-end test; a request to a +development server; a CLI fixture with an expected snapshot; a browser action; +a captured trace replay; a temporary test program around the real function; a +property/fuzz loop; a regression bisector; a comparison between implementations; +or a structured manual action with an observable result. + +Pin clocks, random seeds, filesystem state and dependencies where relevant. +For intermittent failures, measure the reproduction rate, preserve seeds and +stress the suspected boundary. Do not introduce sleeps as the product fix just +because a timing probe makes the problem disappear. For performance, capture a +baseline distribution or profile before bisecting; logs rarely locate a cost +regression by themselves. + +If setup is temporarily blocked, record attempts and the exact missing input +or capability. Continue useful source tracing and fixture preparation, but mark +runtime conclusions unverified. Request only the access or observation actually +needed. Temporary environment failure is not permission to call a static review +a passed runtime check. + +## Test a cause + +1. Reproduce the user's failure at the intended layer. Read the earliest failed + assertion, not only the final exit code. +2. Rank a few plausible causes, each paired with an observation that would + distinguish it from the alternatives. Eliminate hypotheses already + contradicted by the source or environment. +3. Change one variable in a probe. Prefer a debugger, boundary observation or + targeted log over logging the entire system. Mark temporary probes so they + can be removed completely. +4. After two attempts fail to change the same symptom, revisit the cause and + consult an available independent perspective. Provide the failed attempts + rather than asking another reviewer to repeat them. +5. Minimise the reproduction into a regression at the correct seam. Observe it + failing for the product reason, repair the code, then rerun it, its supported + control and the original scenario. +6. Remove temporary instrumentation and owned scratch files after retaining + useful evidence. Explain the causal change and any remaining observation gap. + +A pure-function test may be the right first seam. Claims about admission, +durable state or delivery also need the consuming boundary checked. For +stateful bugs, inspect effects even when the response reports an error. + +## Static-oracle mode + +Use this only when the task genuinely has no possible runtime: for example, +an offline implementation exercise supplied as text. It is a distinct evidence +category, not a workaround for a missing dependency on an otherwise executable +project. Do not claim compilation, test execution or a runtime PASS. + +First reconstruct the contract from the available code. Read documentation, +the inverse function, sibling helpers, constants, exact error variants and test +assertions. Use the established names and types. An encoder paired with an +existing decoder should follow the decoder's field order and byte contract, +rather than an invented “equivalent” representation. + +Then trace each assertion with substituted values. Record exact lengths, +prefixes, units, variants and fields. Follow one concrete value through both +directions of a roundtrip. Check every name exists, every branch returns the +declared type, borrowed/owned conversions match, and integer widths are valid. +“The roundtrip should work” is not a trace. State what remains unknowable +without compiling or running, and provide the first runtime checks for handoff. + +For example, if a visible decoder expects `[version, length, payload...]`, +trace payload `[7, 8]` as `[1, 2, 7, 8]` only if the supplied constants define +version `1` and a one-byte length. Check empty input, maximum length and the +exact overflow error from that same visible contract. This illustrative trace +does not prescribe a new protocol. + +## Broaden only when the evidence warrants it + +When several modules or parallel implementations obscure the cause, use +[diagram diagnosis](diagram-diagnosis.md). For an ambiguous design, inspect +existing decisions and ask a focused question with the likely tradeoff. Do not +walk every possible design branch or require an ADR for a routine local choice. +An ADR is useful for a consequential, surprising decision with real alternatives. diff --git a/skills/visioncraft/references/deepsec.md b/skills/visioncraft/references/deepsec.md new file mode 100644 index 0000000..c925d96 --- /dev/null +++ b/skills/visioncraft/references/deepsec.md @@ -0,0 +1,77 @@ +# Security review through a bounded adapter + +Deepsec is an external reviewer, not part of the skill's reasoning runtime. +Use a compatible installed adapter under the project's source-sharing, model +and spend policy. Running a full paid review after every edit is not the +default. A required security review and a cheap candidate scan are different +checks. + +Compatibility is based on the inspected Deepsec 2.3.10 +protocol. Consult the installed version's own help/documentation before changing +its flags or result interpretation. A later version needs compatibility evidence. + +## Declare the attempt + +Choose exactly one supported scope/mode, the base revision or file list, +required threshold, tool/model configuration, total deadline, capture limits +and a fresh private output directory. Resolve relative input paths against the +invoking directory before an adapter changes working directory. Preserve +relevant dirty/untracked bytes and configuration with the plan. + +Resolve credentials by approved names at execution time. Do not write secret +values into plans, command-line arguments, diagnostics or public evidence. +Explicit malformed configuration is an error, not permission to fall back to +permissive defaults. A host can support absent optional config without treating +an explicitly requested unreadable manifest as absent. + +## Determine completion before counting findings + +Deepsec's inspected protocol overloads exit 1: findings and runtime/input/provider +failure can share it. Interpret it as completed findings only with the pinned +completion path's fresh, nonempty comment from this invocation and a valid +successful export. Exit 0 also needs a valid export. Never use an old comment, +empty fallback array or unrecognised parser output as evidence of a clean run. + +Retain the original export and per-attempt output. Reject malformed rows, +unknown severities and incomplete/truncated capture. Keep severity order and +threshold explicit, including bug categories such as `HIGH_BUG` and `BUG`. +A policy pass means no counted finding crossed that threshold, not zero +findings or a secure system. + +Legacy outcome conventions are 0 for completed policy pass (or separately +labelled scan-only completion), 1 for blocking findings, 70 for runtime/export +error, 78 for disabled/unavailable/configuration refusal, and 124 for deadline. +Use the actual adapter's documented mapping for cancellation and other invalid +input. A scan-only result must not satisfy a required model review. + +## Retain scope and history + +Compare planned files, observed reviewed scope and final changes. Working-diff +mode alone does not establish coverage of untracked inputs. A small diff may +lead a reviewer to inspect a whole file; source traces decide whether a finding +is new, pre-existing or unreachable under the selected configuration. + +Resumed or reused state can export historical findings. Keep the aggregate +unchanged and identify current-attempt observations separately. A fresh run ID +does not revalidate every row. A prior failed attempt's comment cannot prove +this attempt completed. Isolate attempts or use explicit controlled resume +semantics so concurrent reviews cannot overwrite evidence. + +If raw rows lack unique IDs, retain a separate normalised view with IDs tied to +the raw export hash and row location; preserve the mapping. Do not claim this +deduplicates independent runs. Feed findings through +[review evidence](review-evidence.md) and Sealmap dispositions. + +## Validate the failure protocol + +Keep controls for a completed empty review and a completed real finding beside +cases for invalid inputs, unavailable provider, absent/stale completion, +malformed export, unknown severity, timeout and interrupted capture. A gate +that rejects everything is also broken. Test path/argv handling, total deadline +and child cleanup with local controlled executables before replacing a consumer. + +This adapter does not provide a source sandbox, certification or deployment. +Revalidation, dynamic testing and production acceptance remain separate work +when required. Source-bearing artefacts stay private unless publication is +explicitly authorised. [Agentbox](ecosystem-agentbox.md) adds its own integration +policy and legacy-path handling. diff --git a/skills/visioncraft/references/diagram-diagnosis.md b/skills/visioncraft/references/diagram-diagnosis.md new file mode 100644 index 0000000..e766ef4 --- /dev/null +++ b/skills/visioncraft/references/diagram-diagnosis.md @@ -0,0 +1,73 @@ +# Diagnose competing paths with diagrams + +Use this when a failure crosses several modules, there may be multiple writers +or validators, or successive local fixes keep missing the cause. Read actual +source and callers; old architecture drawings are leads, not current evidence. + +## Map the journey + +Partition by concern: request admission, identity, storage, events, rendering, +background processing or another boundary relevant to the bug. Map each in the +same session or delegate independent slices if authorised and available. +Record participants as actual executions; a named logical role is not a worker. + +For each slice retain entry point, selected feature/configuration, consumed +dependency revision, calls, state stores, success/error branches and source +anchors at a full commit. Include shadow paths and unfinished migrations. +A sequence diagram exposes order and effects; a flowchart exposes branching +and authority. Render the diagram to catch syntax/layout problems, then review +its claims against code. Rendering is not semantic verification. + +```mermaid +sequenceDiagram + participant Client + participant Route + participant Policy + participant Store + Client->>Route: Submit operation + Route->>Policy: Check identity and operation binding + Policy-->>Route: Admit or deny + alt admitted + Route->>Store: Durable mutation + Store-->>Route: Commit result + Route-->>Client: Response + else denied + Route-->>Client: Rejection + end +``` + +This is a teaching example, not a source-verified diagram of a product. A real +diagram must also show secondary writes, retries and response construction +where those affect the finding. + +## Compare before merging paths + +Build a small anomaly register: claim, paths/callers, contract differences, +live/partial/retired state, source revision, relevant introducing change, +reproduction and disposition. Compare inputs, outputs, authority, side effects +and compatibility. Similar names do not make two protocols duplicates. + +For each candidate choose an explicit outcome: shared owner with consumer +adapters; intentional policy variants; remove a proven retired path; or retain +an unresolved question. Keep rejected duplicate candidates and reasons so the +next reviewer does not repeat the same investigation. + +## Prove and repair + +Create a failing probe at the smallest real seam, with a valid control. Pure +model tests avoid irrelevant GPU/network setup when they establish the claim. +For admission, persistence or user-visible delivery, also exercise the actual +consumer. Follow discovery links returned by the system rather than guessing +where a resource should live. + +Repair the owning implementation or actual routing. Run shared fixtures through +each affected consumer, including intentional policy differences. Before +deleting a parallel path, inspect callers, feature gates, packaged consumers +and its compatibility role. Correct diagrams and decisions after the code is +committed; preserve historical stamps and append current evidence instead of +rewriting the history of an earlier review. + +When useful for Rust, Sealmap's dense/generated views can expose call edges. +They are extraction aids with unresolved/inferred edges, not proof that a +runtime takes the path. Packs bound context; they have not demonstrated a +general review-quality advantage over full source that fits in context. diff --git a/skills/visioncraft/references/ecosystem-agentbox.md b/skills/visioncraft/references/ecosystem-agentbox.md new file mode 100644 index 0000000..27e210c --- /dev/null +++ b/skills/visioncraft/references/ecosystem-agentbox.md @@ -0,0 +1,71 @@ +# Agentbox integration example + +Agentbox is one consumer of the portable VisionCraft skill and executable. This +reference describes its integration responsibilities; none is a prerequisite +for using VisionCraft in another repository or CI environment. Source pins and +runtime availability must be checked independently after a rebuild. + +## One payload, two harnesses + +Canonical release content lives in `skills/visioncraft/`. Agentbox's source/pin +projection installs that tree into its skills estate and reconciles the selected +Claude Code and Codex registries. Routing descriptions, indexes, stack +projection, preflight and neighbouring skills must use the same canonical name. +Updating only a directory name does not update those consumers. + +Agentbox uses a hard cutover: rewrite callers using the +[source path map](../assets/legacy-paths.json), then remove the old +`build-with-quality` entrypoint and implementation. No old-name skill, redirect +or second full payload remains active. Existing script callers move to the +installed Rust adapter with the required argument/result contract. Verify the +actual installed layout as well as source; a correct pin does not establish +that the rebuilt image contains it. + +## Memory and participants + +Agentbox requires its governed shared-memory MCP, using the actual tool schema, +for project recall and verified lessons. It does not permit a raw database or +CLI fallback that bypasses its embedding pipeline. The portable skill simply +offers a knowledge-integration seam; other hosts need not provide memory at all. + +Agentbox's registered harness workers perform work; coordination records may +only describe roles to observers. Map logical responsibilities to actual +available workers and retain their execution provenance. Host-configured model +defaults and advisors belong to that host. A same-family advisor is not an +independent auditor, regardless of provider spelling or role label. + +## Security adapter and review cadence + +Agentbox supplies toolchain pins, `[security.deepsec]` policy, route/credential +validation and current spend cadence. A rebuild-controlled binary gate and live +policy are different surfaces. Apply explicit per-run overrides according to +the host adapter, and verify migrated callers' flags, exits and receipt paths. +Configuration errors and unavailable tools remain visible non-passes. + +Do not bypass the adapter with an installation/initialisation command that +creates a separate dependency tree, links a hosted service or starts unbounded +model work. Read effective configuration and installed versions. Keep +names-only credential references, private source-bearing output and approved +network routes. Authorisation for one review does not authorise publication of +its source pack. + +## Shared owners in the estate + +Sealmap owns finding receipts, model-family declarations and code-view packs. +Authored diagram topics retain source verification and decision links; +rendering/citation tools check their respective syntax and references. Neither +valid Mermaid nor a valid receipt establishes semantic truth. + +Agentbox's review scheduler and budget ledger remain existing owners. VisionCraft +does not create another spend database, findings store, orchestrator or learning +engine. Its adapters should expose the same recorded outcomes to both harnesses +and ordinary CI consumers. + +## Adoption checklist + +Verify the published crate/bundle, exact source hash, consumer lockfile/build, +all migrated direct paths, both registries, router and picker fixtures, stack/preflight +projection and CI entry point. Then check installed versions and a harmless +end-to-end observation after activation. Local path-patched tests and pinned +image inputs do not prove the running image uses the release. Preserve the +separate publication, adoption and deployment receipts in the existing record. diff --git a/skills/visioncraft/references/edd.md b/skills/visioncraft/references/edd.md new file mode 100644 index 0000000..d22de43 --- /dev/null +++ b/skills/visioncraft/references/edd.md @@ -0,0 +1,113 @@ +# Expectation-driven development + +Use EDD when ordinary acceptance tests leave important intent unstated: ordering, +failure effects, interactions between users, resource limits or subjective +qualities. A requirement such as “helpful error messages” still needs an actual +human judgement; a schema cannot settle it. EDD complements DDD, TDD and BDD. + +## Seven steps + +1. **Formulate.** Describe one coherent behaviour, its boundaries and a + counterexample. Clarify competing requirements before implementing them. +2. **Implement.** Make the change against those expectations and the governing + specification. Start meaningful failing tests where a runnable seam exists. +3. **Produce evidence.** Run representative cases and preserve the invocation, + observed output and exact subject. Do not substitute a narration of intent. +4. **Audit.** Have the required reviewer examine the raw evidence, source and + scope, then attempt a counterexample the producer did not already cover. +5. **Challenge.** Resolve ambiguity, subjective acceptance and residual risk + with the appropriate decision-maker. Prior agreement can supply acceptance; + do not request the same permission again. +6. **Iterate.** Repair the implementation or expectation when evidence exposes a + gap. Retain the earlier result and explain why the new claim differs. +7. **Stabilise.** Turn regression-critical scenarios into permanent checks and + link the expectation to a successful execution of the resulting test. + +Author, coder, evidence producer and auditor describe responsibilities. One +person can perform several for modest work. If project policy requires an +independent auditor, record the real execution identity and actual model family; +calling the same session “auditor” does not create independence. An unavailable +independent reviewer leaves that requirement incomplete. Same-family fallback +may provide advice, clearly labelled, without silently weakening the policy. + +## Write a bounded expectation + +Use [the template](../assets/expectation.md). Record an id, parent requirement, +linked decisions, priority, regression importance, evidence category and author +status. Describe the behaviour precisely enough that a reader can propose an +input that would falsify it. Include in-scope cases, excluded adjacent work and +explicit counterexamples. Do not make every assertion its own administrative +record or combine an entire product into one expectation. + +For example, “discounts work” does not specify operation order. A useful +expectation says that a single percentage discount reduces the subtotal before +tax, names the rounding rule, handles an empty cart, and rejects stacking a +second code without changing the first. Shipping and currency conversion can +have separate expectations. Numbers here must come from the product contract, +not a generic quality template. + +## Evidence categories + +| Category | Retain | What it establishes | +|---|---|---| +| Executable | Command/argv, raw output, timestamp, full revision, relevant input snapshot, configuration, observed effect | Behaviour reached by that execution | +| Partially verifiable | Dry-run/plan/check output plus the same subject fields and an explicit limitation | The checked portion; a staging plan does not establish production behaviour | +| Manual/non-executable | Named observer, exact scenario, captured artefact, time, subject and unresolved conditions | An attributed observation under the project's acceptance policy | + +UI and hardware work are not intrinsically non-executable: use available browser +or device tests when they measure the actual claim. Conversely, a simulation +does not prove the physical device. Classify by evidence available for this +claim, not by the technology's name. + +For a defect reproduction, identify the reached failing assertion and preserve +a valid control in the same supported environment. A compiler error before the +scenario runs is setup evidence. A formatter panic before a replay assertion +does not prove replay. See [review evidence](review-evidence.md). + +## Audit and counterexamples + +Give the auditor the requirement, implementation revision, configuration and +raw observations. Ask them to find a mismatch, not to approve the producer's +story. A separately identified adversarial probe must exercise a plausible +boundary. Repeating the producer's input under another role label is not that +probe. A successful structural receipt check is useful to the auditor but does +not substitute for interpretation. + +Keep unresolved disagreements scoped. Another model can propose a discriminating +experiment; majority agreement cannot establish the result. Escalate a required +decision through the project's existing authority rather than inventing a vote +or new approval mechanism. + +## Freshness and regression coverage + +Evidence belongs to a snapshot. Apply explicit freshness policy across three +separate questions: does the recorded revision resolve and have the required +ancestry; have relevant source/configuration/dependency bytes changed; has the +allowed observation age elapsed? Missing VCS information is unknown. An +unrelated commit need not invalidate evidence. The old thirty-day limit is a +possible project policy, not a universal default. + +A `stabilized_by` reference is useful only if the named check exists, exercises +the expectation and has a matching successful receipt. Merely adding the string +cannot satisfy regression-critical work. If a real regression cannot yet run, +leave the required condition open or obtain an explicit risk decision under the +project's process; do not rename it stable. + +Before treating expectation coverage as complete, check the scoped denominator, +linked observations, actual assertions/effects, required reviewer identity and +probe, freshness, and each required stabiliser. Keep author labels such as +`proven` separate from derived evidence status. + +## Workshop and proportionality + +For shared business logic, use [the workshop agenda](../assets/workshop.md): +agree domain words, draft examples independently, compare conflicts, and have +someone other than the author challenge each important expectation. For a +small repair, write the relevant expectation in the issue or test description +and use the local checks. This method does not mandate a workshop, agents or a +new database for every change. + +EDD is an engineering workflow, not an established proof system. Subjective +criteria, incomplete runtime access and correlated reviewers limit confidence. +Choose the heavier audit loop where the consequences justify it; record which +parts were actually performed. diff --git a/skills/visioncraft/references/evaluation.md b/skills/visioncraft/references/evaluation.md new file mode 100644 index 0000000..608d689 --- /dev/null +++ b/skills/visioncraft/references/evaluation.md @@ -0,0 +1,74 @@ +# Validate the skill without inventing improvement + +Structural checks establish packaging quality. Public example execution +establishes those examples. An independent forward test establishes what that +participant did on its task. Measured improvement requires a separate, controlled +comparison. None substitutes for the others. + +## Structural audit + +Check the entrypoint's portable frontmatter, name/directory parity, concise +trigger description, progressive references, relative-link closure and complete +licence/provenance records. Both target harnesses should discover the same +canonical payload. Inspect migrated callers and the installed layout; the hard +cutover must leave no active old skill or implementation. + +Check every declared runtime feature against a shipped implementation, every +command example against the current executable, and every numeric result +against retained evidence. Logical responsibilities must not be presented as +spawned agents. Configuration without a loader must not be advertised as +enforcement. Missing optional tools remain visible limitations. + +## Public behaviour cases + +These are acceptance cases for authors and reviewers; they are not held-out +material and must not be reported as such. + +| Case | Useful observation | +|---|---| +| A test fails during fixture construction before the claimed replay check | Records setup/observation failure, repairs the fixture and reaches the intended assertion with a supported control | +| A producer fix exists but the consumer lockfile pins an older release | Reports the actual consumed version and keeps source repair separate from adoption | +| Required auditor is unavailable; a same-family advisor responds | Retains advice and unmet independence without fabricating a pass | +| Reviewer exits with a stale comment and no valid fresh export | Preserves incomplete/error state rather than inventing an empty clean review | +| A two-line ordinary change needs a local regression | Avoids an unnecessary workshop, fleet, paid review or tracking database | +| A genuine offline text-only implementation task has no runtime | Substitutes concrete values through the visible contract and reports static limits without executed-test claims | +| A hardware/user observation is required | Separates simulated/partial/manual observation and actual acceptance authority | +| Two similar validators have different credential lifetimes | Compares contracts/callers and retains intentional differences | +| Rejected content remains reachable by known identifier | Checks publication stores/readers and migration rather than only hiding search results | +| A new registry release exists after local path-patched tests | Exercises the real consumer pin before claiming adoption | + +## Independent forward test + +Give a separate participant a realistic request, this candidate skill and the +minimum raw project material. Do not provide the suspected defect, intended +answer, planned fix or earlier conclusions. Use an isolated owned checkout and +restrict side effects to the evaluation's authorised scope. Keep its actual +trajectory, artefacts, commands and any inability to execute. + +Grade whether the participant reached the relevant behaviour with a valid +control, respected subject/version and authority boundaries, avoided false +closure and completed the requested task proportionately. Do not grade mere +presence of headings or quoted skill vocabulary. A refusal-only strategy must +fail the supported control. Changes to the skill should address demonstrated +mistakes rather than accumulating universal rules for every hypothetical risk. + +A coordinator owns this pass and reports whether it ran. This file is a +procedure and public oracle; it contains no claim that forward testing passed. + +## Measured tuning + +Freeze the baseline skill, candidate, task set, evaluator and budgets before +comparison. A curator independent of implementation should create sealed +held-out cases with different fixtures and withhold their answers. If a case +is shown during debugging, move it into regression material and replace it in +the held-out set. + +Use paired conditions with the same task/tool access and record actual model +identities, order and resource budgets. Replicate enough to observe variability; +the initial programme calls for at least three trials per item. Keep training, +validation and final test separate. Do not leak another arm's outcome or the +reference solution into optimisation prompts. + +Report per-item outcomes, denominators, uncertainty, cost and failures alongside +any aggregate score. Structural compliance or a successful public example does +not demonstrate empirical uplift. No such uplift is claimed by this package. diff --git a/skills/visioncraft/references/methodologies.md b/skills/visioncraft/references/methodologies.md new file mode 100644 index 0000000..7a8c206 --- /dev/null +++ b/skills/visioncraft/references/methodologies.md @@ -0,0 +1,69 @@ +# Domain boundaries, decisions and tests + +## DDD where the domain needs it + +Identify the language users employ, the invariants that belong together, and +the systems that own them. A bounded context makes the meaning of a term +explicit; it is not automatically a service or repository. Draw a context map +where upstream/downstream ownership or translations can explain a defect. + +Use entities for identity across change and value objects for validated values. +An aggregate should protect a small coherent set of invariants. Reference other +aggregates by identity rather than sharing mutable internal state. Domain +events make cross-context effects visible, but delivery, ordering and retry +guarantees still need an implementation and tests. A repository interface can +express persistence needs without requiring a generic framework. + +Choose these patterns because they clarify the domain. A small CLI or local +repair does not need a full domain model, speculative factory or event bus. + +## Decisions with an inspectable boundary + +Create an ADR for a consequential tradeoff that would otherwise surprise a +maintainer. Record context, alternatives, chosen constraints, consequences, +status and the decision authority. Use the project's existing format and IDs; +[the template](../assets/adr.md) is available when none exists. + +Relationships such as `depends_on`, `amends` and `supersedes` help readers follow +change. Validate that references resolve and statuses make sense. A consistent +decision graph still does not establish agreement with source code. + +For records claiming implemented behaviour, identify the inspected full commit +and nonempty governed paths. A staleness check should detect changes to those +paths, dependencies or policies that could affect the claim. Verify the gate +actually selects records: an opt-in check with no opted-in paths protects +nothing. Staleness is a review queue, not a verdict that the decision is wrong. + +Land the code before stamping its decision record. Compare governed paths with +the inspected revision; do not stamp the preceding commit while changing the +same implementation in the documentation commit. Proposed/rejected designs can +have no verified implementation revision. Record acceptance according +to existing project authority, including an already authorised decision. + +When a path changes, distinguish cosmetic movement, semantic change and unknown +impact. Recheck the actual contract before refreshing the stamp. Reopen the +decision if behaviour or a tradeoff changed. An available independent review +can help with material drift; it does not replace the evidence or impose an +extra approval ceremony for every documentation update. + +Optional graph/search tools can index these records. The Markdown or existing +decision store remains the chosen authority; VisionCraft does not create an +ADR database or assume an uninstalled plugin's commands work. + +## TDD and BDD + +Choose a behavioural seam. In the red phase, observe failure for the expected +reason with valid setup and a supported control. In green, implement the +smallest sufficient change. Refactor only while relevant tests remain green. +Use descriptive scenario names and arrange/act/assert structure where it helps. + +Unit tests establish local rules; contract tests compare producer and consumer; +integration and end-to-end tests establish the journeys they actually reach. +Avoid tests that mirror a literal constant or an implementation branch without +testing meaningful behaviour. Keep failure effects and negative cases beside +valid success cases. + +BDD scenarios can express shared examples; EDD records broader intent and +counterexamples before they become stable tests. Link regression-critical +expectations to executed checks as described in [EDD](edd.md). An isolated +source repair, a passing test and a deployed fix are separate facts. diff --git a/skills/visioncraft/references/migration.md b/skills/visioncraft/references/migration.md new file mode 100644 index 0000000..f18d6f2 --- /dev/null +++ b/skills/visioncraft/references/migration.md @@ -0,0 +1,25 @@ +# Moving from build-with-quality + +VisionCraft is the portable successor method and executable contract. Agentbox +cuts over all active callers once the new implementation passes its gates, then +removes the old entrypoint; no compatibility period or redirect remains active. +[The path map](../assets/legacy-paths.json) accounts for all +28 original files and distinguishes preserved resources, rewritten guidance, +host-owned adapters and explicit retirement. + +Uppercase activation/protocol/example files now live under `assets/` or +`references/`. Rust resource paths remain available beneath the canonical skill. +Agentbox's direct-path migrations belong to its adapter and installation +tests. [The integration reference](ecosystem-agentbox.md) identifies the related +registries, routers, stack projection and runtime checks. + +Agentbox removed the old TypeScript/npm API in September 2026; +VisionCraft does not revive its classes, factories or imports. The old +`config/skill.yaml` described policy but had no discovered current loader. It is +retired rather than carried forward as inert runtime configuration. Use the +actual released CLI/library schema and the host's declared policy. + +Historic role records, automatic learning, consensus labels and performance +targets do not describe implemented VisionCraft services. Useful engineering +responsibilities remain in [roles](roles.md); host features remain integrations. +Recorded prior evidence keeps its original version and conclusions. diff --git a/skills/visioncraft/references/quality-gates.md b/skills/visioncraft/references/quality-gates.md new file mode 100644 index 0000000..bbe8b24 --- /dev/null +++ b/skills/visioncraft/references/quality-gates.md @@ -0,0 +1,83 @@ +# Select and interpret quality gates + +A gate is a project policy evaluated against observations. It is neither a vote +nor a guarantee that the system is correct. Choose required checks before the +result is known, from the changed behaviour, consumers and governing policy. + +## Applicable check families + +| Check | Establish the policy and evidence | +|---|---| +| Pre-implementation | Scope, important expectations, interfaces, relevant decisions and supported environment | +| Pre-merge | Meaningful regressions/controls, supported features, formatting/lints, contract compatibility and scoped coverage | +| Security | Threat boundary, actual source selection, completed reviewer/scanner result, known severity vocabulary and threshold | +| Accessibility | Relevant interaction requirements, tested user journeys and applicable standard criteria; automated findings plus required manual observations | +| Resilience | Explicit failure model, workload, recovery/loss limits and observations during network/resource/dependency faults | +| Evidence coverage | Original expectation denominator, actual observations, required independence, freshness and executed stabilisers | + +Coverage percentages, compliance claims, latency budgets and reliability targets +are not universal defaults. A line-coverage number does not show that assertions +test the right behaviour. Use mutation testing or targeted counterexamples when +they answer a real uncertainty. Defect prediction needs a named model, labelled +data and a measured result; the skill itself has no prediction engine. + +## Readiness profiles + +A prototype can explicitly exclude deployment, independent review or resilience +work when the task permits it; retain correctness checks for supported behaviour +and do not describe the result as production acceptance. Ordinary maintenance +usually needs a focused regression, compatibility checks and required repository +gates. A critical protocol/state change may need EDD, consumer fixtures, an +independent audit and recovery/migration acceptance. The profile selects work; +it does not pre-populate successful evidence. + +## Workflow through the gates + +Clarify intent and domain boundaries, record the expectations that matter, +implement with a testable feedback loop, produce evidence, perform applicable +review and challenge, stabilise important scenarios, then assess release and +consumer acceptance. Use an advisor before locking a difficult interface, +after repeated failed repairs, or over the final diff when available and useful. +A same-family advisor does not discharge an independent-audit requirement. + +Checks may run alongside implementation when independent, but preserve a final +subject revision and configuration. Paid external review follows the current +project's cadence; do not run it automatically after every increment. A check +before later edits must not be presented as review of the final diff. + +## Outcome dimensions + +Record process completion separately from evaluator judgement. A process can +finish with an error, a scanner can produce incomplete output, and a threshold +can pass while lower-severity findings remain. Required missing, skipped, +unavailable, timed-out, contradictory or inconclusive evidence prevents a +complete pass. Optional findings remain visible even when they do not block. + +Display the required checks, effective threshold, source selection and original +denominator. Changing requiredness or scope is a policy change, not earned +completion. A zero-check gate is not evidence of readiness. Preserve failed +invocations and capture failures rather than interpreting them as empty results. + +## Imported findings + +Preserve the raw export. Determine the actual assertion, consumer version and +effects before choosing a disposition. Code defects enter the regression loop; +incorrect diagrams need source-backed corrections and rendering/citation checks; +accepted risks need the appropriate decision reference; missing evidence stays +inconclusive. Use [review evidence](review-evidence.md) and the existing register. + +Sealmap 0.4 supplies adjacent finding receipts and independent delivery +attestations. `sealmap review check` validates schema/artefact integrity; +`--require-resolved` additionally requires no unverified or inconclusive findings. +It must not force a fabricated rejection. Its library validator checks structure +only; the CLI additionally resolves and hashes files. These checks do not judge +the truth of the observation or the authority of a self-reported decision. + +## Finish at an evidenced boundary + +Report changed behaviour, meaningful tests and their scope, required gates that +passed or remain unresolved, and accepted risks. Keep source, test, merge, +publication, consumer adoption and deployed behaviour separate. Save reusable +lessons through the host's existing knowledge system if available, with source +and limits. Do not claim automatic learning or improved success rates from +writing a lesson. Archive private evidence before deleting owned scratch work. diff --git a/skills/visioncraft/references/review-evidence.md b/skills/visioncraft/references/review-evidence.md new file mode 100644 index 0000000..2388768 --- /dev/null +++ b/skills/visioncraft/references/review-evidence.md @@ -0,0 +1,162 @@ +# Review evidence: establish cause, subject and effect + +Use this when turning an external audit, code review or failing regression into +work. It is an intake method for substantial findings, not an instruction to +audit the entire estate for every small edit. + +## Reach the claimed failure + +Read the earliest failing assertion and stack. A replay test that fails while +formatting its first response has established a response failure, not replay. +Retain that observation, repair or isolate the prerequisite, and reach the +intended assertion. Keep a valid success control: rejecting all requests can +make rejection-only tests pass. + +An existing test may encode a defect. File existence can conceal unusable +permissions; successful creation can conceal a missing secondary record. Before +changing expected output, identify the contract and inspect the resulting state +or access decision. Separate fixture repairs from product repairs. + +Classify setup failure, observation error, product failure and uncertainty. +Unavailable runtime access is not evidence against a finding. Reject only with +counterevidence or a source trace that contradicts the claim. Preserve the +reviewer's original bytes and make corrections in supported dispositions or an +adjacent keyed receipt. + +## Trace the consumer and authority + +Follow the real entry point to the called helper, build features and dependency +version. A canonical verifier can be present but unused. A function called +`verify` might check a signature while omitting body binding or replay policy. +Use the consumer lockfile, package cache or vendored source before assuming a +sibling repository's newest commit runs in that consumer. + +For source-pinned packages, reconstruct the archive's layout and use its actual +lockfile. Check each consumer whose pin moves. One workspace can compile while +another fetches an old revision or exposes an incompatible dependency type. +Stale local comments do not establish third-party behaviour. + +Shared code still needs its relevant policy checked: aliases, raw versus +reserialised bodies, optional binding, clock windows, cache scope and errors. +Record deliberate compatibility differences and run their fixtures. Wiring a +previously broken reader can expose data to an authority the original broken +lookup concealed; test access through the repaired route and a correctly wired +component control. + +Hidden discovery is not denied access. Try a known identifier, and inspect +shared transport settings that may override component policy. A subprocess +probe establishes that layer; end-to-end exposure needs the consuming route. + +## Publication, quarantine and migration + +If a verdict occurs after storage, enumerate all readers: raw and rendered +views, protocol routes, local object APIs, indexes, exports, archives and +backups. A transport denial does not govern the other readers. Integrity +validation does not by itself stop publication. + +Keep candidate bytes outside every served namespace until approval, then +publish only the approved records/closure. Test a valid published control, +rejected known-identifier access, and reads while validation is pending. For +old data, test migration from a pre-repair fixture. Removing an index row does +not remove already addressable objects. Define conflicts and recovery, preserve +approved roots and quarantine recoverable old data outside served storage. + +## Consolidate the actual shared contract + +Compare inputs, outputs, trust boundaries, effects and callers before calling +paths duplicates. A reusable credential and a one-request token can have +different replay rules; a login challenge need not implement request signing. +Classify each path as live, partly wired, retired or already repaired at the +examined revision. Retain rejected duplication candidates with reasons. + +Trace reads and writes together. An unwritten settings store, vectors never +populated for retrieval, or membership deletion that leaves an identity index +is a broken journey even if isolated components pass. Prefer the existing +shared owner and run the same contract fixtures through real adapters. Pin time +and bytes for signed fixtures. Shared fixtures can prevent drift before shared +implementation is practical. + +Follow discovery links emitted to clients in integration tests. Writing to a +guessed path can hide a faulty advertised one. After mutation, exercise the +consuming read or policy decision with allowed and denied callers. + +## Effects survive error responses + +Trace identity, admission, mutation, primary/secondary durable writes, response +construction and delivery. Observe state on both sides of boundaries where an +error follows a completed effect. Error does not imply rollback; success does +not establish delivery or settlement. + +Separate token replay from operation idempotency. Retrying the same signed +token, using a fresh token for the same operation, retrying after restart and +retrying on another replica are different tests. Check whether rejection spends +credentials and whether stores commit together. A file lock does not establish +transactional effects or distributed replay admission. + +## Reviewer completion and threshold semantics + +An empty list is meaningful only after a completed review with a valid export. +Missing completion, parser mismatch, quoted success markers, quota errors, +truncated output and export failure remain errors. If a tool reuses an exit +code for findings and runtime failure, require fresh completion evidence from +that invocation. Keep both empty-review and real-finding positive controls. +Unreadable/corrupt spend records must not become an empty paid-review ledger. + +Compare reviewer agreement only for equivalent bytes, scope, visible register +and recognised actual model families. Provider aliases, filenames and similarity +clusters do not demonstrate independence. Agreement ranks hypotheses; it does +not verify them. + +Inspect effective severity categories, threshold, skipped checks, feature set +and tested revision. A threshold pass may coexist with material uncounted +categories. Distinguish pre-existing defects, regressions, accepted risks and +unverified findings; do not quietly lower the threshold for a green result. +Likewise, a changed hunk can trigger whole-file analysis without making every +finding a regression introduced by that hunk. + +Resumed work may export old findings with new run metadata. Compare current +completion evidence and actual source to the aggregate; a refreshed run ID is +not item-by-item revalidation. Keep raw history and current dispositions apart. +Severity labels alone do not prove exposure: identify reachability, selected +build, caller authority and demonstrated effect. Fail-closed refusal may still +be a functional defect in a supported journey. + +## Build and capture failures + +Inspect the actual target and features: a narrow test can build a binary, while +disabling defaults can remove requirements. Supply needed pinned inputs in an +isolated checkout. Do not replace authentication or persistence dependencies +with stubs just to make checks green. Before calling a failure baseline-only, +retain diagnostics and establish that the relevant files were unchanged. +Report full-gate failure separately from passing focused tests. + +Budget disk alongside CPU when several workspaces compile. After exhaustion, +check source writes and receipts for truncation before retrying. Restore known +reviewed bytes, rerun affected checks, and reclaim only owned caches after +preserving evidence. Another worker's build directory is not spare space. + +## Close out without changing the claim + +Keep finding IDs and the raw export hash bound to the same bytes. Evidence of +an unrelated successful consumer cannot support adoption when the real consumer +failed. Preserve source-bearing prompts/logs outside publication directories; +permission to call a model is not permission to publish its inputs. + +A source review, rendered diagram, imported finding, test, merge and deployed +repair are different observations. A scope reduction changes the denominator +and earns no completion credit. Handoffs retain trigger, exact revision/config, +command and raw result, effect, disposition and remaining acceptance conditions +in the existing project register. + +For changed contracts, test minting helpers, examples and downstream callers as +well as the verifier. Check immutable build artefacts, upload, registry release, +consumer lock resolution and running activation independently. After local +path-patched integration, remove that patch and exercise the actual released +consumer source/checksum before claiming adoption. Reuse checksum-verified +release artefacts where the release contract requires them; do not silently +substitute locally compiled bytes for a reviewed toolchain pin. + +Naming/discovery repairs do not migrate prior state. Define precedence, +conflicts and recovery for records under the old convention. For permission +data, verify both retained owner access and denied access after migration. +Record producer repair and migration acceptance separately. diff --git a/skills/visioncraft/references/roles.md b/skills/visioncraft/references/roles.md new file mode 100644 index 0000000..a7aedce --- /dev/null +++ b/skills/visioncraft/references/roles.md @@ -0,0 +1,60 @@ +# Responsibilities and actual participants + +Assign responsibility before assigning a model. The catalogue below preserves +the old role vocabulary for migration and planning; these labels do not create +workers, choose models or establish tools are installed. A single maintainer +can perform several roles sequentially. Delegate only when available and +authorised, with a bounded task, owned files and a clear return artefact. + +| Role labels | Responsibility and observable result | +|---|---| +| architect | Domain/interface choices, constraints and decision record when warranted | +| coder | Implementation and causal explanation of the diff | +| reviewer | Scoped findings grounded in source and evidence | +| browser-agent | An actual browser journey and retained observations | +| deployer | Authorised release/activation operations and separate receipts | +| expectation-author | Behaviour, boundaries and counterexamples agreed with the requester | +| tdd-stabilizer | A meaningful permanent test linked to the expectation and an executed result | +| test-strategist | Appropriate seams, fixtures, controls and applicability | +| unit-test-generator | Local behavioural tests | +| integration-test-generator | Tests through real component boundaries | +| e2e-test-generator | Supported end-user journeys and their environment limits | +| coverage-analyzer | Measured coverage and uncovered important behaviour | +| mutation-tester | Evidence that selected tests detect meaningful altered behaviour | +| defect-predictor | Only an available, validated prediction tool; otherwise exploratory review without prediction claims | +| flaky-test-hunter | Reproduction rate, environment/seed and a diagnosed source of instability | +| chaos-engineer | Bounded fault experiments and effects | +| resilience-validator | Recovery, loss and service-level observations under a specified workload | +| evidence-producer | Commands, raw observations and exact input/configuration identity | +| evidence-auditor | Independent examination and an additional counterexample probe when required | +| security-architect | Trust boundaries and threat assumptions | +| security-implementer | Tested changes to relevant controls | +| security-tester | Authorised boundary probes with supported controls | +| sast-scanner | Completed static-analysis results and their scope | +| dast-scanner | Authorised dynamic checks against a named target | +| compliance-auditor | Evidence against applicable criteria; not an automatic certification | +| memory-indexer | Host-provided knowledge maintenance, if available and authorised | +| trajectory-tracker | Actual attempts and outcomes retained under the host's data policy | +| reasoning-bank-manager | Curated reusable patterns with provenance and limits | +| cross-project-transfer | Check whether a prior lesson's assumptions apply to this consumer | +| sona-optimizer, q-learning-optimizer | Historical extension labels; no corresponding runtime is supplied here | +| tdd-red-phase | A failing meaningful case with correct setup | +| tdd-green-phase | The smallest sufficient repair and passing case/control | +| tdd-refactor-phase | Simpler structure with preserved observed behaviour | + +The original catalogue contains 34 labels. Coordination labels such as +`unified-coordinator`, `event-bridge` and `mcp-coordinator` also appeared in a +descriptive config; they remain host responsibilities, not additional workers. + +Record actual execution/agent IDs, model identities, inputs, tools and outputs +when participant provenance matters. A role label or provider alias cannot +establish independent review. If policy requires a different model family, +verify that relationship for the actual producer and auditor. Same-family +advice remains useful and is labelled as such. Unknown identities do not earn +independence credit. + +An advisor is useful before difficult interface decisions, after repeated +failed repairs and over the final diff. If no advisor exists, reassess the +hypothesis yourself and record any unmet required review. Do not invent a +successful consultation. For one real integration, see +[Agentbox](ecosystem-agentbox.md). diff --git a/skills/visioncraft/references/rust/NOTICE.md b/skills/visioncraft/references/rust/NOTICE.md new file mode 100644 index 0000000..dd4134a --- /dev/null +++ b/skills/visioncraft/references/rust/NOTICE.md @@ -0,0 +1,53 @@ +# Notice — vendored BeautifulRust material + +`steering.md`, `review.md`, `port.md`, everything under `sources/` and both files under +`lints/` are adapted from **BeautifulRust** by Morgan Linton. + +- Upstream: https://github.com/morganlinton/BeautifulRust +- Pinned revision: `a9cdcfa94d1330c0d41c7f67764c5f7786fbb71d` (vendored 2026-10-31) +- Upstream paths: `skills/rust-best-practices/SKILL.md` and `references/*.md`, + `skills/rust-review/SKILL.md`, `skills/rust-port/SKILL.md`, `lints/lints.toml`, + `lints/clippy.toml` + +The `sources/` digests are verbatim. The three skill bodies have the estate overlay +added: crypto, publication, feature-set and MSRV rules, the dead-code exception for +ports, and hand-off into build-with-quality's findings intake. Links to upstream paths +point at the vendored copies. The Bevy digest, the evals and the benchmark were not +vendored. To refresh, diff the pinned revision against upstream `main` and re-apply the +overlay, which is marked as section 0 in `steering.md` and `port.md` and section 6 in +`review.md`. + +## Licence + +MIT License + +Copyright (c) 2026 Morgan Linton + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +## VisionCraft migration note + +The notice above is retained in full from the pinned Agentbox import and +describes that import's estate changes. VisionCraft preserves the source digests +and lint assets byte-for-byte. Its new portable section 0 in steering/port, +section 6 in review, dead-path guidance and adjusted links replace the earlier +estate overlay. All thirteen Rust language sections remain available. Original +BeautifulRust material remains MIT; newly written VisionCraft additions follow +the project's MIT OR Apache-2.0 terms. File-level pins and modification records +are supplied in `assets/provenance.json` at the skill root. diff --git a/skills/visioncraft/references/rust/lints/clippy.toml b/skills/visioncraft/references/rust/lints/clippy.toml new file mode 100644 index 0000000..6365ddc --- /dev/null +++ b/skills/visioncraft/references/rust/lints/clippy.toml @@ -0,0 +1,12 @@ +# BeautifulRust clippy configuration. Copy to your crate or workspace root, next to +# Cargo.toml, alongside the [lints] block from lints.toml. + +# Flag any function with a bool parameter, not just functions with four or more. +# A bool argument is unreadable at the call site (report(true)) and can't grow a +# third mode; use a two-variant enum or two methods instead. +max-fn-params-bools = 0 + +# Allow unwrap, expect, and printing in tests, where a panic is the assertion. +allow-unwrap-in-tests = true +allow-expect-in-tests = true +allow-print-in-tests = true diff --git a/skills/visioncraft/references/rust/lints/lints.toml b/skills/visioncraft/references/rust/lints/lints.toml new file mode 100644 index 0000000..17047b8 --- /dev/null +++ b/skills/visioncraft/references/rust/lints/lints.toml @@ -0,0 +1,73 @@ +# BeautifulRust drop-in lints +# +# Paste this into your Cargo.toml (or replace [lints] with [workspace.lints] in a +# workspace root and add `[lints] workspace = true` to each member). It makes clippy +# enforce the rules from ../steering.md (BeautifulRust rust-best-practices) that a machine can check. +# Everything is "warn"; make CI strict with: +# +# cargo clippy --all-targets -- -D warnings (plus the feature set CI uses) +# +# Silence a lint locally with a reason, which the config below requires: +# +# #[expect(clippy::unwrap_used, reason = "the regex is a literal and always compiles")] +# +# Lints marked [lib] fit libraries; applications can drop them. + +[lints.rust] +unsafe_op_in_unsafe_fn = "warn" # each unsafe op needs its own unsafe block +missing_debug_implementations = "warn" # every public type implements Debug +missing_docs = "warn" # [lib] document every public item +unreachable_pub = "warn" # pub items that aren't actually exported +rust_2018_idioms = { level = "warn", priority = -1 } # 2018-edition idioms, e.g. Formatter<'_> + +[lints.clippy] +# Groups first, at lower priority so the individual settings below win. +all = { level = "warn", priority = -1 } +pedantic = { level = "warn", priority = -1 } + +# Panics: return errors, and give every intentional panic a reason. +unwrap_used = "warn" # use ?, or expect("why this cannot fail") +expect_used = "allow" # expect with a reason is the sanctioned form +panic_in_result_fn = "warn" # a fn returning Result shouldn't also panic +missing_panics_doc = "warn" # [lib] document reachable panics under # Panics +missing_errors_doc = "warn" # [lib] document failures under # Errors +missing_assert_message = "warn" # assert! says what went wrong (quiet inside #[test]) + +# Suppressions must explain themselves and expire when no longer needed. +allow_attributes = "warn" # prefer #[expect] over #[allow] (needs rust-version 1.81+) +allow_attributes_without_reason = "warn" # every suppression says why (needs rust-version 1.81+) + +# Unsafe must be justified. +undocumented_unsafe_blocks = "warn" # // SAFETY: comment on every unsafe block +multiple_unsafe_ops_per_block = "warn" # one unsafe operation per block + +# API shape. +fn_params_excessive_bools = "warn" # bool parameters: use an enum or two methods +struct_excessive_bools = "warn" # many bool fields: use an enum or bitflags +clone_on_ref_ptr = "warn" # write Rc::clone(&x) so cheap clones are visible +redundant_clone = "warn" # a clone whose original is never used again +rc_buffer = "warn" # Rc / Rc>: use Rc / Rc<[T]> + +# Evolution. +exhaustive_enums = "warn" # [lib] exported enums are #[non_exhaustive] (quiet in binaries) + +# Idioms. +string_add = "warn" # build strings with format! or push_str, not + +wildcard_imports = "warn" # no glob imports (use super::* in tests is allowed) + +# Output and debugging leftovers. +dbg_macro = "warn" +todo = "warn" +print_stdout = "warn" # [lib] libraries log, they don't print +print_stderr = "warn" # [lib] libraries log, they don't print + +# Casts that silently lose information. +as_conversions = "warn" # prefer From / TryFrom +cast_possible_truncation = "warn" +cast_sign_loss = "warn" + +# Pedantic lints that are mostly noise in practice, or that the skill disagrees with. +module_name_repetitions = "allow" +must_use_candidate = "allow" +module_inception = "allow" # a leaf module named after its main item is fine +enum_glob_use = "allow" # use Enum::* inside a function that matches on it diff --git a/skills/visioncraft/references/rust/port.md b/skills/visioncraft/references/rust/port.md new file mode 100644 index 0000000..4c1a745 --- /dev/null +++ b/skills/visioncraft/references/rust/port.md @@ -0,0 +1,149 @@ + +# Rust port + +Adapted from BeautifulRust's `rust-port` skill (MIT, see [NOTICE.md](./NOTICE.md)). + +The goal is the Rust a Rust developer would have written to solve the same problem, with +the same observable behavior. A line-by-line transliteration (C written in Rust syntax, +or Python with `Box`) compiles but keeps every problem the original had and adds +the borrow checker on top. Port the behavior, not the structure. + +## 0. Establish the benefit and boundary + +Port when it serves an actual maintenance, distribution, safety or performance +need. Reuse language-specific wrappers when the underlying capability is only +available there; changing a few lines around Blender, GIS or machine-learning +libraries may add complexity without improving the system. Record the reason. +Use maintained cryptographic libraries and vectors rather than translating a +bespoke primitive. Scope behaviour changes explicitly alongside compatibility. + +## 1. Understand the original before writing anything + +1. **Read the code and its tests**, and anything that calls it, if you have it. +2. **List the observable behavior**: every public function, its inputs, its outputs, and + every way it can fail. Include the quiet parts, which are where ports go wrong: + ordering of results, how ties break, what happens on empty input, whitespace and case + handling, integer limits, and what counts as an error versus a valid edge case. +3. **Note what is incidental**, meaning things the original only does because of its + language: manual memory management, out-parameters, `NULL` returns, global state, + fixed-size buffers, a class that exists only to group functions, or `isinstance` + checks. These don't carry over. +4. If the original has a bug or an ambiguity, keep its behavior, flag it in the porting + notes, and let the user decide. A port is not the place to silently fix things. +5. **Remove only established dead paths.** Check callers, build features, + configuration, tests and packaged consumers before omission. Record the + evidence and deletion separately from changed supported behaviour. + +## 2. Port the tests first + +Translate the original tests into Rust tests before porting the implementation. Keep one +Rust test per original test, with a name that maps back to it, so a reader can check +coverage. The tests are the definition of "same behavior". If the original has no tests, +write characterization tests from the behavior list in step 1. + +## 3. Design the Rust API, then implement it + +Decide the public types and signatures from the behavior list, not from the original's +shape. Then implement against the ported tests. + +### From C and C++ + +| In the original | In Rust | +|---|---| +| `malloc`/`free`, `new`/`delete`, `create`/`destroy` pairs | Owned types (`String`, `Vec`, `Box`) dropped automatically; `Drop` for anything else | +| `NULL` meaning "absent" | `Option` | +| Error codes (`-1`, `ERR_*` defines), `errno` | `Result` with an error enum, one variant per code, implementing `Display` and `std::error::Error` | +| Out-parameters (`int *err_line`, `long *out`) | Return values: put the data in the `Ok` value or the error variant | +| Flag bitmasks (`FLAG_A \| FLAG_B`) | An options struct with named fields and `Default`, or the `bitflags` crate; never a raw `u32` | +| `char *` plus length, `strcmp`, `strcasecmp` | `&str`/`String`, `==`, `eq_ignore_ascii_case` | +| Pointer plus count, iterator by index | Slices, iterators | +| Fixed-size buffers and their truncation | Growable types; drop the limit unless the limit is behavior | +| `#define` constants and macros | `const`, enums, and functions | +| Global or static mutable state | A struct the caller owns | +| `strtol` and friends | `str::parse` with the matching integer type; map parse failures to your error enum | + +Don't write `unsafe` or use raw pointers unless the port must talk to C through FFI, and +then confine it as [steering.md](./steering.md) section 8 describes. + +### From Python + +| In the original | In Rust | +|---|---| +| An exception hierarchy | One error enum (or one per area) with a variant per exception class; data attributes become variant fields | +| `None` as a value | `Option` | +| Strings used as a closed set (`kind in ("build", "test")`) | An enum, with `FromStr` and `Display` for the text form | +| Dicts or classes used as records | Structs with named fields | +| `dict` iteration order (insertion order is guaranteed) | `Vec` or an ordered map when order is observable; a plain `HashMap` silently changes output order | +| Duck typing, `isinstance` | Traits or enums | +| Unbounded `int` | A sized integer chosen on purpose, with overflow handled (`checked_*`) where input can be large | +| `sorted(..., key=...)` | `sort_by_key` or `sort_by`; both are stable, like Python's | +| `str.splitlines()`, `strip()`, `isalnum()` | `lines()`, `trim()`, `char::is_alphanumeric`; check edge cases such as `\r\n`, Unicode, and empty strings against the original | +| `try`/`except` around a parse | `?` with a mapped error, or `match` on the `Result` | + +### From Go, JavaScript, and TypeScript + +- Go `(value, error)` returns become `Result`; `nil` becomes `Option`; interfaces become + traits; goroutines and channels become threads with `std::sync::mpsc` or async tasks, + depending on what the original needs. +- JavaScript `null` and `undefined` become `Option`; thrown errors become `Result`; plain + objects become structs; numbers become a sized integer or `f64`, chosen on purpose. + +## 4. Keep the port proportionate + +A port that matches the original on every possible input is usually the wrong goal. +Match it on the inputs it actually receives, and use Rust's standard library for the rest. + +- **Don't reimplement the source language's runtime.** Use `str::lines`, `str::trim`, + `str::parse`, and `char` methods, not hand-written copies of Python's `splitlines`, + `strip`, `int()`, or `repr()`, or of C's locale-dependent `isspace` and `strtol`. Where + Rust's behavior differs only on exotic input, such as Unicode digits, non-ASCII + whitespace, or unbounded integers, list the difference in the porting notes instead of + coding around it. Write a compatibility shim only when the user says those inputs occur. +- **Don't grow the API.** Port the public surface the original has, plus the standard + trait impls Rust callers expect (`Debug`, `Clone`, `Display`, `Error`, `FromStr`, + `Default`, and `IntoIterator` for collections). Skip builders, `Index` impls, + `FromIterator`, `Extend`, and custom iterator types unless the original's callers need + them. +- **Keep the algorithm unless it's wrong.** Swap in a different algorithm only to fix a + real problem, such as quadratic behavior on realistic input, and say so in the notes. +- **Check the size.** Count code lines, excluding tests, comments, and doc comments. A + port from C or C++ usually lands near the original's size. A port from Python or + JavaScript usually lands at two to three times the original, because types, error + enums, and their trait impls are explicit in Rust. Much more than that usually means one + of the three habits above. + +Differential testing against the original is worth doing, but a few dozen realistic and +edge-case inputs answer the question. A fuzzing harness over millions of inputs usually +just finds exotic divergences that belong in the notes. + +## 5. Verify + +Run these if a Rust toolchain is available, and fix everything before reporting: + +```bash +cargo build +cargo test +cargo clippy --all-targets -- -D warnings # feature set per steering.md section 0 +``` + +Every ported test must pass. If the original's tests can be run too, run them and compare +results on the same inputs. + +## 6. Write the porting notes + +Alongside the code, write a short `PORTING.md` that a reviewer can check in a few +minutes: + +- **API mapping:** a table from each original function or type to its Rust equivalent. +- **Test mapping:** each original test and the Rust test that covers it. +- **Deliberate differences:** anything that now behaves differently and why, such as an + out-of-memory error that no longer exists, a fixed buffer limit that's gone, or exotic + input where Rust's standard library behaves differently from the original's. +- **Preserved quirks:** odd behavior kept on purpose, so nobody "fixes" it by accident. +- **Removed dead code:** each deleted path and the evidence it was unreachable. +- **Verification:** which commands you ran and their result, or a plain statement that + you couldn't run them. + +For the style of the Rust itself, follow [steering.md](./steering.md). Ported tests support the +behavioural parity they reach. Retain actual commands, outputs, subject revision +and configuration; unexecuted tests remain unverified. diff --git a/skills/visioncraft/references/rust/review.md b/skills/visioncraft/references/rust/review.md new file mode 100644 index 0000000..06326f5 --- /dev/null +++ b/skills/visioncraft/references/rust/review.md @@ -0,0 +1,181 @@ + +# Rust review + +Adapted from BeautifulRust's `rust-review` skill (MIT, see [NOTICE.md](./NOTICE.md)). +Review Rust code against the same rules [steering.md](./steering.md) uses for writing +it, and report what to change. The output is a review, not a rewrite: the reader decides +what to fix. Only rewrite code when the user asks for that. + +## 1. Decide the scope + +- **What to read.** Review exactly what the user pointed at: a file, a module, a crate, + or a diff. For a diff, review the changed lines and anything they break, not the whole + file. +- **Library or application.** Check for a `lib.rs`, `pub` items used by other crates, or + a published `Cargo.toml`. Library code is held to the API-design rules strictly. + Application code gets the simplicity rules instead: concrete types, `anyhow`-style + errors, and no speculative generality. Say which you assumed at the top of the report. +- **The edition and MSRV**, from `Cargo.toml`, so you don't recommend features the + project can't use. +- **Frameworks.** If the crate depends on `bevy` or `bevy_ecs`, fetch the Bevy digest + first (see the References list at the end of [steering.md](./steering.md)). It lists the Bevy + conventions to leave alone (by-value system parameters, the prelude, plain-data + components) and the ECS bugs to look for. + +## 2. Run the tools first, if you can + +If a Rust toolchain is available, run these from the crate root and fold the results into +the report. They catch the mechanical issues, which leaves you free for design. + +```bash +cargo fmt --check +cargo clippy --all-targets -- -W clippy::pedantic # feature set per steering.md section 0 +cargo test +``` + +Don't paste raw clippy output. Group repeated warnings into one finding, and skip pedantic +lints that don't matter for this code. If the tools aren't available, say so in the report +and review by reading. + +## 3. What to look for, in priority order + +Work through these in order. The first two categories are where real bugs live. + +**Correctness and soundness** + +- Undefined behavior: an `unsafe` block without a `// SAFETY:` comment, `transmute` to + cast enums or extend lifetimes, `unsafe impl Send`/`Sync` used to silence the compiler, + or a safe function that can cause UB through safe calls (unsound). +- Panics on reachable paths: `unwrap()`, `expect()`, indexing, `as` casts that wrap, or + integer overflow, wherever input from outside can reach them. +- Trait contracts: a hand-written `Ord` with a derived `PartialEq`, or `Hash` that + disagrees with `Eq`. These silently corrupt `BTreeMap`, `HashMap`, `sort`, and `dedup`. +- Lock hazards: a `MutexGuard` held across `.await` or returned to a caller, user + closures called under a lock, or a poisoned lock recovered with `into_inner`. +- ECS bugs in Bevy code: two queries that can reach the same component mutably (a + B0001 panic on the first frame), systems that read each other's results with no + order between them, and deferred `Commands` read back before they apply. +- Destructors that panic, block, or can fail. + +**Error handling** + +- Errors that callers can't use: `()`, `String`, or `Box` as a library's + public error type, an error enum without `Display` and `std::error::Error`, or + `anyhow::Error` in a library's public API. +- Errors that lose information: `map_err(|_| ...)`, no `source()`, or messages without + the path, line, or value that failed. +- Panics used for expected failures, or `catch_unwind` used as control flow. + +**API design** (strict for libraries) + +- Parameters: `&String`, `&Vec`, or `&Box` instead of `&str`, `&[T]`, or `&T`; a + `bool` parameter in a public signature; ownership taken and then cloned, or a borrow + cloned internally to get ownership; `impl Into` in application code, or on a library + function too rarely called to justify a copy per argument type. +- Return types: a library function that collects into a `Vec` only to return it, when an + iterator would do. Owned results are fine when callers need ownership or random access, + or when building the collection is the function's job. +- Visibility: public fields that should be private, `Rc`, `RefCell`, or `Arc` in public + signatures, or third-party types leaking into the API. +- Missing standard traits: `Debug` on public types, `Display` on errors, `Default` next to + a zero-argument `new()`, and `FromStr` instead of an ad-hoc `from_str` method. +- Naming: `get_` prefixes on getters, `as_`/`to_`/`into_` that don't match their cost and + ownership, and `Manager`/`Service`/`Util` names. +- Evolution: public enums or structs that should be `#[non_exhaustive]`, or traits that + should be sealed. + +**Idiom and clarity** + +- Clones that exist only to satisfy the borrow checker. +- Check-then-unwrap (`if x.is_some() { x.unwrap() }`), and `match` where a combinator is + clearer, or the reverse. +- String building with `+`, hand loops that are clearer as iterators, or iterator chains + long enough to need a loop. +- `HashMap` iteration order leaking into output or tests. +- `#![deny(warnings)]` in source, `#[allow]` without a reason, and glob imports of + external crates (a framework's documented prelude, such as `bevy::prelude`, is fine). + +**Documentation and tests** + +- Public items without docs, and docs that restate the name. +- Missing `# Errors`, `# Panics`, or `# Safety` sections where they apply. +- Doc examples that use `unwrap()` instead of `?`. +- Logic with no tests, or tests that only restate constants. + +[steering.md](./steering.md) and its [sources/](./sources/) digests hold the full rules and +their reasoning, including the portable scope rules (crypto, publication, feature sets). Read +the relevant one when a finding needs a rule you're unsure of. A hand-rolled crypto +primitive is always **Must fix**. + +## 4. Write the report + +Use this structure: + +~~~markdown +# Rust review: + + + +## Must fix +### 1. (`src/file.rs:42`) +**Rule:** +**Problem:** +**Fix:** +```rust + +``` + +## Should fix +### 2. ... + +## Consider +### 3. ... + +## What's already good +- <2 to 4 specific things the code does well> +~~~ + +How to sort findings: + +- **Must fix** means a bug, a soundness hole, a reachable panic, or an API mistake that + becomes a breaking change once published. +- **Should fix** means it works but violates a rule with a real cost, such as worse error + messages, harder testing, or a confusing API. +- **Consider** means style, naming, and polish. + +Rules for each finding: + +- **Cite a location** as `file:line` for every finding (write `whole file` for a finding + that has no single location, such as missing tests), and cite the rule with its source: + an API Guidelines code such as `C-GETTER`, an Effective Rust item number, a Microsoft + guideline code such as `M-PANIC-ON-BUG`, a clippy lint name, or "Google Rust Style + Guide". A reader should be able to look the rule up. +- **Show the fix as code**, kept to the lines that change. Don't rewrite whole functions. +- **Group repeats.** One finding for "eight `unwrap()` calls on parse results", listing + the lines, rather than eight findings. +- **Respect intent.** If something looks deliberate, such as a documented quirk or a + comment explaining it, mention it under Consider with the trade-off. Don't mark it + Must fix. +- **Keep it proportionate.** For a short file, five to ten findings is plenty. Don't pad + the list, and don't hide a real bug among style nits. +- **"What's already good" is required.** It tells the author what to keep and makes the + rest credible. + +## 5. Offer the lints + +If the project lacks a `[lints]` table, or has an empty one, end the report by suggesting +the vendored lints config ([lints/lints.toml](./lints/lints.toml) and +[lints/clippy.toml](./lints/clippy.toml)). It makes clippy catch most of the +mechanical findings above automatically. Name two or three findings from this review that +it would have caught. + +## 6. Carry findings into implementation + +A review proposes claims to investigate. Preserve its raw findings and apply +the [evidence intake](../review-evidence.md): establish the assertion, actual +consumer revision and effects with supported controls. Record reproduced, +contradicted, accepted and inconclusive claims distinctly. Inability to run a +probe is inconclusive, not rejection. Keep setup repairs separate from product +fixes and a successful review separate from proof of correctness. diff --git a/skills/visioncraft/references/rust/sources/effective-rust.md b/skills/visioncraft/references/rust/sources/effective-rust.md new file mode 100644 index 0000000..2990d3e --- /dev/null +++ b/skills/visioncraft/references/rust/sources/effective-rust.md @@ -0,0 +1,196 @@ +# Effective Rust (digest) + +Source: *Effective Rust* by David Drysdale (O'Reilly, 2024), free online at +https://www.lurklurk.org/effective-rust/ . Thirty-five items on writing Rust well. +Read this when weighing alternatives: generics vs trait objects, `Result` vs panic, +iterators vs loops, how to get past the borrow checker, dependency and CI policy. +The book targets Rust 1.70 to 1.76; anything it calls "upcoming" has long since landed. + +## Types (Items 1-9) + +1. **Use the type system to express your data structures.** Replace "must be (0,0,0) if + monochrome" comments with an enum that carries the data. `Option` for absence, never + sentinels. Fallible results are always `Result`. An enum instead of a `bool` + parameter when a third option could ever arrive; a newtype when it will always be + boolean. +2. **Use the type system to express common behavior.** Accept trait types rather than + concrete ones when flexibility matters. For closures use the most general `Fn*` bound + that works: `FnOnce` if called once, `FnMut` if it mutates, `Fn` otherwise. Prefer + `Fn*` bounds to bare `fn` pointers, which cannot capture state. Marker traits + (a method-less `StableSort: Sort`) express guarantees a signature cannot. +3. **Prefer `Option` and `Result` transforms over explicit `match`.** `map`, `and_then`, + `ok_or`, `map_err`, `unwrap_or_else`, `as_ref()`, and `?`. `Result` beats `Option` + when the failure could carry useful information. `unwrap` and `expect` are decisions + to panic (Item 18). +4. **Prefer idiomatic `Error` types.** Implement `std::error::Error` (requires `Debug` + + `Display`; `source()` exposes causes). Preserve sub-errors with an enum plus a `From` + impl per inner error (`thiserror` generates this). When they need not be preserved, + applications use `anyhow`; keep `anyhow` out of library public APIs. A bare `String` + cannot implement `Error` (orphan rule), so wrap it. +5. **Understand type conversions.** Implement `From` (gives `Into` free); `TryFrom` only + when a conversion can fail. In bounds use `Into` so both kinds of impl are + accepted. Prefer `from` / `into` over `as`, which silently permits lossy casts, except + where exact cast semantics are the point (C interop). +6. **Embrace the newtype pattern.** `PoundForceSeconds(f64)` vs `NewtonSeconds(f64)` + can't be mixed; an alias doesn't prevent it. Newtypes also let you implement a foreign + trait for a foreign type. Cost: inner trait impls are lost and must be re-derived or + forwarded. `#[repr(transparent)]` keeps the layout identical. +7. **Use builders for complex types.** `Default` with `..Default::default()` when most + fields have sensible defaults; a builder when there are optional or validated fields. + Consuming builders (`fn x(self) -> Self`) are most ergonomic but can't be staged + conditionally or reused. `&mut self` builders allow staging but need a named `let` + binding, and a repeatable `build(&self)` must construct fresh values. +8. **Familiarize yourself with reference and pointer types.** `&T` is a pointer the + compiler guarantees valid, aligned, and borrow-checked. `Box` for single-owner heap + data; `Rc` / `Arc` for shared ownership (with `Weak` to avoid cycles); `Cell` / + `RefCell` or `Mutex` / `RwLock` for interior mutability. `RefCell` moves borrow checks + to runtime, so use `try_borrow` where a panic is unacceptable. Choose the mutation + granularity you need: `Rc>>` vs `Rc>>`. +9. **Consider iterator transforms instead of explicit loops.** Source, adapters + (`filter`, `take`, `map`, `zip`), consumer (`sum`, `fold`, `find`, `any`, `collect`). + Propagate the first error by collecting into `Result, _>` and applying `?`. + Keep a loop when the body is large or does several jobs, when early returns are + awkward inside closures, or when the transform is forced. Measure when it matters. + +## Traits (Items 10-13) + +10. **Familiarize yourself with standard traits.** Derive `Clone`, `Copy`, `Debug`, + `PartialEq`, `Eq`, `PartialOrd`, `Ord`, `Hash`, `Default` when every field supports + them; hand-implement only where the derived behavior is wrong. Skip `Clone` for + unique-access resources and secret key material; `Copy` only when a bitwise copy is + valid and fast. Pair `Eq` with `PartialEq` (not for floats), keep `Hash` consistent + with `Eq`, never ship `PartialOrd` without a matching `Ord`. +11. **Implement `Drop` for RAII patterns.** Any type holding a resource that must be + released (file descriptor, lock, raw memory) implements `Drop`. Scope guards with + blocks so locks are not held longer than needed. `drop` can't return an error, so + provide a separate fallible `release()`. Call `drop(x)`, never `x.drop()`. +12. **Understand the trade-offs between generics and trait objects.** Prefer generics. + Monomorphization gives static dispatch and speed but one code copy per type (bigger + binaries, slower builds). Trait objects (`&dyn`, `Box`) use one copy plus a + vtable and suit heterogeneous collections, code-size or compile-time limits, or code + loaded at runtime. Object safety: no generic methods, no `Self` in args or returns + beyond the receiver, unless marked `where Self: Sized`. +13. **Use default implementations to minimize required trait methods.** Few required + methods; defaults for everything derivable (as `Iterator` builds 50+ methods on + `next()`). Defaults can carry bounds (`cloned()` only for `Clone` items). Adding a + defaulted method is usually backward compatible. + +## Concepts (Items 14-20) + +14. **Understand lifetimes.** A reference may not outlive its referent. Elision covers + a single input reference lending to the output, and methods lending `&self`'s + lifetime. Otherwise name them. A struct holding a reference needs a lifetime that + propagates to every container, so prefer owning data. `'static` is for globals or + deliberately leaked data (`Box::leak`). +15. **Understand the borrow checker.** Any number of `&T` or exactly one `&mut T`, never + both, and non-lexical lifetimes end a reference at its last use. Coping tactics: + extend a temporary with a named `let` or shorten with a block; split a complex + expression into typed intermediates; redesign ownership by cloning small immutable + data, using an owning `Vec` with indices (fragile), or `Rc` / `RefCell` with `Weak` + back-pointers. Avoid self-referential structs (`ouroboros` if unavoidable). +16. **Avoid writing unsafe code.** Use std and crates.io first, where battle-tested + `unsafe` already lives (`Rc`, `Mutex`, `Pin`, `cxx`). When unavoidable: confine it to + a small wrapper with a safe API, document each block's preconditions in a safety + comment, minimize each block, enable `unsafe_op_in_unsafe_fn`, write extra tests, + run Miri. +17. **Be wary of shared-state parallelism.** `Send` / `Sync` and the borrow checker + eliminate data races in safe code; deadlocks and logic races remain. Prefer message + passing. When sharing: keep data with linked invariants under one lock, keep lock + scopes small, never call closures while holding a lock, never return a `MutexGuard` + to a caller, add deadlock detection to CI. A documented lock hierarchy is a last + resort. +18. **Don't panic.** Prefer `Result`; panic is for unrecoverable bugs or corrupted + state. Rule of thumb: `panic!`, `unwrap()`, `expect()` are acceptable when you + control `main`, because no further caller exists. Where a panic is justified, pair + an infallible function (documented under `# Panics`) with a fallible one. + `catch_unwind` is not an exception substitute: it does nothing under + `panic = "abort"` and can leave state inconsistent. Use it at FFI boundaries only. +19. **Avoid reflection.** No general runtime reflection. `type_name` is diagnostic only; + `TypeId` / `Any::downcast_ref` work only on values already wrapped as `dyn Any`. + Encode required behavior as traits, marker traits for properties, derive macros for + compile-time generation. +20. **Avoid the temptation to over-optimize.** Design for usability first: a type that + owns a `Vec` avoids lifetime propagation, and copying small data is usually fine. + Add allocations or clones only after benchmarks show they matter; `Rc` / `Arc` with + `RefCell` / `Mutex` are legitimate tools. Exception: `Copy`. Derive it for small + bitwise-copyable types and never for large or non-trivial ones. + +## Dependencies (Items 21-26) + +21. **Understand what semantic versioning promises.** `"1.2.3"` means `^1.2.3`; `"~"` + allows patches only; `"="` pins; `"*"` accepts anything. Breaking changes: removing + public items, adding a variant to a matchable enum (unless `#[non_exhaustive]`), + adding a public field to a publicly constructible struct, making a trait + non-object-safe, adding a blanket impl. License and default feature set are API. + Deprecate in a minor release before removing in a major one. +22. **Minimize visibility.** Private by default; `pub(crate)`, `pub(super)`, + `pub(in path)` before `pub`. Widening later is minor; narrowing is breaking. Keep + fields private; `pub` on an enum or trait exposes all variants or methods. +23. **Avoid wildcard imports.** Don't glob-import crates you don't control; a minor + release can add a clashing name (error E0034). Fine for `use super::*` in tests, + modules you own, and a deliberately curated prelude. If you glob a dependency anyway, + pin it. +24. **Re-export dependencies whose types appear in your API.** A caller on a different + semver-incompatible version of `rand` gets a confusing "trait bound not satisfied". + Re-export (`pub use rand;`) so callers can name the matching version, and think hard + before exposing foreign types at all. +25. **Manage your dependency graph.** Cargo allows semver-incompatible versions of a crate + to coexist, never two compatible ones. Commit `Cargo.lock` for binaries. Prefer + `"1"` or `"1.4.23"` to `"=1.2.3"` or `"*"`. Use `cargo tree` (`--invert`, + `--duplicates`, `--edges features`), `cargo-deny`, `cargo-udeps`. Every dependency + costs build time, binary size, and supply-chain exposure, including `build.rs` and + proc macros. +26. **Be wary of feature creep.** Features must be additive because Cargo unifies them + across the graph. Don't feature-gate public struct fields or trait methods. Feature + names share a namespace with crate names. Each independent feature doubles the + configurations; CI should cover the combinations that matter. Model: a `std` or + `alloc` feature on a `no_std` base. + +## Tooling (Items 27-32) + +27. **Document public interfaces.** `///` and `//!`, cross-reference with `` [`Name`] ``, + `# Examples`, `# Panics`, `# Safety` sections. Describe what the signature cannot + express (preconditions, errors, panics, why), not the types. `cargo doc --open`; + consider denying `broken_intra_doc_links`; avoid rushed docs written only to silence + `missing_docs`. +28. **Use macros judiciously.** Only when a function or generic cannot do the job, or to + keep parallel code in sync (one table generating an enum plus `group()`, `text()`, + `TryFrom`). Macros can insert `return`, `?`, or mutations at the call site, so keep + control flow visible, and bind expression arguments with `let` to avoid + re-evaluation. Prefer a derive macro to a proc macro that emits a new type. Check + `strum`, `enumn`, `num_enum` first. +29. **Listen to Clippy.** Keep the code warning-free. Fix rather than suppress; where a + lint is genuinely wrong, a narrow `#[allow(clippy::..)]`. `cargo clippy -- -Dwarnings` + in CI. Read the full lint list, including default-off lints such as + `as_conversions`, to learn idiom. +30. **Write more than unit tests.** Unit tests in `#[cfg(test)] mod tests` (see private + items); integration tests in `tests/` (public API only); doc tests; examples + (`cargo test --examples`). Benchmarks with `std::hint::black_box`. `cargo-fuzz` for + untrusted input. Write a failing test before fixing a bug. Test every feature + combination and platform with distinct code. +31. **Take advantage of the tooling ecosystem.** `cargo fmt`, `check`, `clippy`, `doc`, + `bench`, `update`, `tree`, `metadata`; `rust-analyzer`; `cargo-expand`, + `cargo-tarpaulin`, `cargo-udeps`, `cargo-deny`, `cargo-semver-checks`, Miri. Wire + useful tools into CI; fast, false-positive-free ones into the editor. +32. **Set up CI.** Build, run every test type, `cargo clippy -- -Dwarnings`, + `cargo fmt --check`, `cargo doc`, `cargo-deny`. Pin the toolchain with + `rust-toolchain.toml`, build every feature combination, check the MSRV, build a + `no_std` target, detect generated-code drift. Remove flaky tests; make every check + runnable locally; add a CI check for a process problem before fixing it. + +## Beyond standard Rust (Items 33-35) + +33. **Consider making library code `no_std` compatible.** `core` has `Option`, `Result`, + iterators; `alloc` adds `Box`, `Rc`, `Arc`, `Vec`, `String`, `BTreeMap`. `HashMap` + and `Mutex` need the OS. Often just `std::` path changes and `BTreeMap`. Guard with a + CI cross-compile (`thumbv6m-none-eabi`); expose additive `std` / `alloc` features, + never a `no_std` feature. Prefer `try_reserve` where memory is limited. +34. **Control what crosses FFI boundaries.** Calls into C are `unsafe`. `extern "C"` + blocks, `#[link]` or `build.rs`, sized types, `#[repr(C)]`, `CString` / `CStr`. + Allocate and free on the same side; wrap C-owned pointers in an RAII type; check null + and return `Result`; keep unsafe inside the wrapper. Exported functions need + `extern "C"`, `#[no_mangle]`, a unique prefix; `Box::into_raw` / `from_raw` for + ownership transfer; never return stack pointers; stop panics with `catch_unwind`. +35. **Prefer `bindgen` to manual FFI mappings.** Generate declarations from C headers + (`--allowlist-function`), `include!` the output, and fail CI if a regenerated file + differs. Large C APIs: a raw `xyzzy-sys` crate under a safe `xyzzy` crate. C++: `cxx`. diff --git a/skills/visioncraft/references/rust/sources/google-rust-style-guide.md b/skills/visioncraft/references/rust/sources/google-rust-style-guide.md new file mode 100644 index 0000000..e408370 --- /dev/null +++ b/skills/visioncraft/references/rust/sources/google-rust-style-guide.md @@ -0,0 +1,208 @@ +# Google Rust Style Guide (digest) + +Source: https://google.github.io/styleguide/rustguide.html . Google's internal guide, +also adopted by Android, Chromium, and Fuchsia. It defers to the official Rust Style +Guide and API Guidelines and adds rules on top. API-design rules are binding for library +code and a strong recommendation for application code, which "should generally favor +simplicity and directness over broad reusability". Read this for formatting, imports, +module layout, accessor naming, and the application-vs-library distinction. Rules +specific to Chromium or Fuchsia builds are omitted below. + +## Background and goals + +Readability over writeability; automation (large-scale changes should be mechanical); +consistency with the Rust ecosystem; rules must pull their weight. Follow the official +Rust Style Guide and API Guidelines unless this guide conflicts. rustfmt enforces most +formatting automatically. + +## Code organization + +- Prefer small crates, ideally but not necessarily a single file. Larger crates are + allowed for orphan-rule coherence or foundational libraries. Decide crate boundaries + before submodules; the root may re-export from leaf submodules. +- Name a leaf module after its primary item: `Foo` gives `mod foo` / `foo.rs`. +- Non-leaf modules contain only `mod` declarations and re-exports. Small "ties things + together" code is tolerated. Leaf modules may include `mod tests`. +- No glob imports, except at reviewer discretion: `use super::*` in inline modules, + `use Enum::*` in enum method bodies, `pub use submodule::*` in non-leaf modules. + Avoid defining preludes. +- One module per `use` statement (rustfmt `imports_granularity = Module`): no `::` + inside braces. + + ```rust + use foo::bar::{Bar, Baz}; // OK + use foo::{Foo, bar::Bar}; // avoid + ``` + +- Import traits inside function bodies unless the trait is used throughout the file. +- Qualify free function calls by module (`mem::transmute(y)`, not `transmute(y)`), but + use types and traits unqualified (`Regex`, not `regex::Regex`). Exceptions: ambiguous + names such as `io::Error` (or `use std::io::Error as IoError`), large type groups, + macros and generated code. + +## Formatting + +- Always run the formatter. Recommended rustfmt settings: `max_width = 100`, + `hex_literal_case = Lower`, `format_macro_matchers = true`. +- `#[rustfmt::skip]` only for deliberate manual alignment or generated code, never for + personal style. + +## Ownership and borrowing + +- Avoid `Rc` / `Arc`; prefer unique ownership. Exception: when the alternative is + unreasonably complex, a review judgment call. +- Borrow rather than `.clone()`. Clone when a real deep copy is needed or borrowing + becomes excessively complex, and weigh performance. Cloning `Rc` / `Arc` is expected. + +## Function inputs and outputs + +- Accept the most flexible borrowed type: `&[T]` not `&Vec`, `&str` not `&String`, + `&T` not `&Box`, `Option<&T>` not `&Option` (clippy `borrowed_box`, `ptr_arg`). +- Library code returns iterators (concrete or `impl Iterator`) instead of `Vec` and + accepts `impl IntoIterator` when only iterating. Application code may return or take + `Vec` / `&[T]` when simpler. Exceptions: callers need an owned vector, random + indexing, or the function's purpose is building a collection. +- `impl Into` parameters only where call-site ergonomics are paramount, weighed + against code bloat. Application code should almost never use them. +- Use an `enum` instead of a `bool` parameter when the purpose isn't obvious. If you + keep a `bool`, add an inline comment at the call site. +- Errors, chosen by API contract: `Option` for obvious failures (`checked_add`); + `Result` when the caller needs details (`fn open_file(path: &Path) -> Result`); `panic!` for bugs and violated invariants, which must be fixed in the + code, not handled at runtime. Developer-facing binaries may panic on non-fatal + errors; tests may panic for assertions. + +## Types + +- Use a newtype rather than an alias for notable semantic differences, a type needing + its own API, a possible future change of underlying type, or type safety + (`Day` / `Month` / `Year`). +- Prefer named fields over tuples, since `.0` and `.1` get confusing. Exceptions: + single-field newtypes and very local contexts. + +## Traits + +- Add trait impls when needed. Low-level library code anticipates needs; application + code adds them on demand. +- Implement the std trait instead of a custom method: `impl FromStr for Foo`, not + `fn from_str` (clippy `should_implement_trait`). Keeping both is acceptable. +- Use `#[derive]` wherever it can express the impl. +- Library code accepts generics (`T: Trait`, `impl Trait`) over `dyn Trait`, except when + code size matters. Reasons: vtable indirection, no inlining, and some traits are not + dyn-compatible (generic functions, associated functions without `self`, functions + returning `Self`). +- Define a trait only for generic programming, for accepting or returning + `impl` / `dyn Trait`, or as an extension trait. Otherwise use an inherent impl. + Don't use traits merely to organize code. +- Extension traits: suffix `Ext`, sole purpose is adding methods (not for generics or + `dyn`), owned by the team that owns the extended type. +- Trait guidance: types with public fields implement traits all subfields implement. + Error types: `Copy` when possible. `Copy` whenever it will clearly stay `Copy`; + `Clone` for most types except external resources; `Default` when there is a `new()` or + default state (clippy `new_without_default`); `PartialEq` over `Eq` unless you need + reflexivity; `PartialOrd` over `Ord` unless you need a total order; map keys get + `Hash` and `Eq`, plus `Ord` if there is a clear total order. +- Pair an important `From` impl with an inherent `::new()`, `::new_from_foo()`, or + `::from_foo()`. +- Bag-of-options structs with all-public fields implement `Default`, enabling + `..Default::default()`. + +## Concurrency + +- Never reach inside a poisoned mutex, "no matter how tempting". +- Library code should not start threads itself. + +## Macros + +Preference order: plain functions, types, traits, and modules; then `macro_rules!`; +then other codegen; then `proc_macro`. Weigh IDE and code-search costs, dialect +creation, and difficulty of large-scale changes. + +## Naming + +- Methods follow std style: `as_`, `to_`, `into_` with the matching `self` convention + (clippy `wrong_self_convention`). +- Lifetimes should be descriptive, especially on types. Exceptions: generic abstractions + like `Cow`, `'_`, and single-character names for simple input/output relationships. +- Generic parameters: short, related to what they represent, ideally the letter from the + most important bound. `T` / `U` for APIs meant for almost any type. +- Constructors: `new()` or `new_with_foo()`; `try_new()` if fallible. Value-to-value + conversions: `from_foo()` with a `From` impl. +- Avoid abbreviations outsiders won't know, including acronyms and letter-dropping. + Exceptions: Wikipedia-common terms and clear cases like `IpAddr`. + +## Documentation + +- Document public APIs; consider the `missing_docs` lint. +- Include examples somewhere in the crate, not necessarily on every function. +- Document panics caused by malformed input, and invariants of unsafe functions and + traits. +- Use capitalization and punctuation. Don't explain language basics. Comments must add + information: `/// Removes an element.` on `remove_element()` is bad; omit it or allow + the lint. Enum variant docs are often omittable. +- `///` for items; `//!` at the top of a file for modules and crates; Markdown; `//` for + implementation notes, TODOs, and commented-out code. Mixing `///` and `//` on one item + is fine: + + ```rust + /// Finds the first `FooItem` with the given `name`, or `None` if not present. + // TODO(issue-12345): `name` should be &str, not String. + ``` + +- Prefer plain doc comments over macro-generated docs. + +## Other Rust features + +- **Unsafe**: don't write it unless safe code cannot do the same. Wrap it in a safe + abstraction, isolate it (ideally in its own crate with few dependencies), add a + `SAFETY:` comment, and justify it, with benchmarks if performance is the reason. +- **Unstable features**: don't use them. +- **Accessors**: `foo()` returns the value or a reference, `foo_mut()`, `take_foo()`, + `set_foo(T)`, `replace_foo(T) -> T`, and `with_foo(|f| ..)` / `with_mut_foo(|f| ..)` + for closure access. Closure accessors suit interior-mutability wrappers (`Mutex`, + `RefCell`) or follow-up validation where `set_foo` can't be used. +- If you implement `len()`, also implement `is_empty()` (clippy `len_without_is_empty`). +- Don't access `#[doc(hidden)]` items you don't own. +- Mark a public function `const` only if it will stay `const`; removing `const` is + breaking. +- Overload operators only for their mathematical or logical meaning, not as sugar. +- `#[non_exhaustive]` on public enums and public-field structs used across teams. + Exceptions: stable ontologies (`Color`), two-state enums, or a commitment to fixing + breakage with a large-scale change (clippy `exhaustive_enums`). +- `#[must_use]` on functions when ignoring the return is a misuse (pure functions like + `HashMap::get()`) or the return carries errors or critical info; not needed if the + return type already has it (`Result`). On types returned by such functions: error + types and lazy computations. +- Run no code before `main()` (no `ctor` crate). + +## Implementation concerns + +- Don't overuse inference. Add explicit types for `.into()`, `.parse()`, and complex + iterator results. Prefer typed variable declarations to turbofish; use `_` where the + compiler forces a turbofish. +- Pattern-match instead of check-then-unwrap: `if let Some(value) = option { .. }`, not + `is_some()` followed by `unwrap()`. +- Use `expect("reason")` over `unwrap()` when a panic is unavoidable. +- On `#[non_exhaustive]` enums, list every variant you handle, with a wildcard for the + rest. Use `if let` or `let .. else` when you care about one variant + (lint `non_exhaustive_omitted_patterns`). +- Add context strings to `assert!`, especially when a human will see the failure or to + distinguish API misuse from bugs: + + ```rust + assert!(self.stream.is_some(), "Call connect() before executing queries"); + ``` + + Don't repeat the condition as the message. +- Avoid long or complex iterator chains. Don't put a chain in a `for` header; bind it to + a variable first. Avoid `for_each`. Short chains are fine: + `values.iter().any(|&v| v > threshold)`. +- Don't call `panic::catch_unwind` in first-party code, except as defense in depth that + is never relied on, and only where `panic = "unwind"` applies. +- Use `format!` / `write!` to concatenate more than two strings (`format!("{a}{b}{c}")`) + and for substitutions instead of `str::replace`. + +## Tests + +Use the codebase's test framework. Tests may use panics for assertions. Tests live in a +`mod tests` inside leaf modules. diff --git a/skills/visioncraft/references/rust/sources/microsoft-rust-guidelines.md b/skills/visioncraft/references/rust/sources/microsoft-rust-guidelines.md new file mode 100644 index 0000000..d4ecd16 --- /dev/null +++ b/skills/visioncraft/references/rust/sources/microsoft-rust-guidelines.md @@ -0,0 +1,269 @@ +# Microsoft Pragmatic Rust Guidelines (digest) + +Source: https://microsoft.github.io/rust-guidelines/ (version 2026.6, MIT licensed). +Ninety guidelines with `M-` codes, written for teams shipping Rust at scale, with a +chapter aimed at AI coding agents. Read this for error struct design, panic policy, +unsafe policy, async, workspace layout, performance, and what makes code easy for an +agent to work with. "Must" guidelines are hard constraints; "should" allows judgment; +the spirit counts over the letter. + +## Universal + +- **M-UPSTREAM-GUIDELINES**: follow the Rust API Guidelines, Style Guide, Design + Patterns, and the UB reference. Especially C-CONV, C-GETTER, C-COMMON-TRAITS, C-CTOR + (provide `Foo::new()` even with `Default`), C-FEATURE. +- **M-STATIC-VERIFICATION**: compiler lints, clippy, rustfmt, cargo-audit, cargo-hack, + cargo-udeps, and Miri as check-in gates. Enable `[lints.rust]` such as + `unsafe_op_in_unsafe_fn` and `missing_debug_implementations`, the clippy groups at + `priority = -1`, and restriction lints like `undocumented_unsafe_blocks`, + `allow_attributes_without_reason`, `map_err_ignore`. +- **M-LINT-OVERRIDE-EXPECT**: `#[expect(clippy::x, reason = "...")]` for local + overrides; an unfulfilled `expect` warns, so stale suppressions are caught. `#[allow]` + only for generated code and macros. +- **M-PUBLIC-DEBUG**: derive `Debug` on public types. Types holding secrets get a + hand-written `Debug` (`UserSecret(...)`) plus a unit test asserting the secret never + appears in output. +- **M-PUBLIC-DISPLAY**: types meant to be read, especially errors and string wrappers, + implement `Display`. Same redaction rules as `Debug`. +- **M-SMALLER-CRATES**: when in doubt, split into more crates (faster builds, no cycles). + `web_server`, `web_client`, `web_protocols` rather than one `web` crate with modules. +- **M-WEASEL-WORDS**: no `Service`, `Manager`, `Factory` suffixes. `Bookings` or + `BookingDispatcher`; `Builder` instead of `Factory`; disposal is `Drop`, not a manager. + Repeatable instantiation takes `impl Fn() -> Foo`. +- **M-SHORT-NAMES**: at most two short words per identifier. No module name baked into a + type (`foo::Id`, not `foo::FooId`). +- **M-REGULAR-FN**: associated functions are for instance creation. Computation with no + receiver is a free function, not `Database::check_parameters(p)`. +- **M-DOCUMENTED-MAGIC**: magic values get a comment on why the value was chosen, the + effects of changing it, and the external systems involved. Prefer a named `const` with + a doc comment. +- **M-LOG-STRUCTURED**: structured events with message templates, named + `..`, OpenTelemetry attribute names, PII redacted. Don't + pre-format with `format!`. + +## Libraries: interoperability + +- **M-TYPES-SEND**: public types and the futures they produce are `Send`. Assert with + `const _: () = assert_send::();`. An `Rc` held across `.await` makes a future + `!Send`. +- **M-ESCAPE-HATCHES**: wrappers around native handles provide + `pub unsafe fn from_native(..)` plus `into_native` / `to_native`, with documented + safety requirements. +- **M-DONT-LEAK-TYPES**: prefer std types in public APIs. Third-party types only behind a + feature flag (`serde`) or with substantial benefit. +- **M-FOREIGN-REEXPORTS**: don't `pub use` another crate's items; users depend on it + directly. Exceptions: umbrella crates, technical splits, hidden macro paths. +- **M-IMPL-ASREF**: parameters may take `impl AsRef` / `AsRef` / + `AsRef<[u8]>` when ownership isn't needed. Struct fields hold `String`, `PathBuf`. +- **M-IMPL-RANGEBOUNDS**: accept `impl RangeBounds`, not `(low, high)` pairs, so + callers write `1..3`, `1..`, `..`. +- **M-IMPL-IO**: write sans-IO functions. Synchronous one-shot I/O takes `impl Read` / + `impl Write`; runtime-agnostic async takes `futures::io::AsyncRead`. + +## Libraries: UX + +- **M-SIMPLE-ABSTRACTIONS**: service-level public types don't expose nested type + parameters. `Service` is fine; `Service>` is not. +- **M-AVOID-WRAPPERS**: keep `Rc`, `Arc`, `Box`, `RefCell` out of public APIs; use `&T`, + `&mut T`, `T`. Smart pointers only when fundamental or benchmarked. +- **M-DI-HIERARCHY**: prefer concrete types, then generics over narrow traits, then + `dyn Trait` wrapped in a custom struct (`DynamicDataAccess(Arc)`). + Don't port a C# `IDatabase` into `Rc`. Test doubles: an enum with a + `Mock(MockCtrl)` variant. +- **M-ERRORS-CANONICAL-STRUCTS**: errors are situation-specific structs, not one global + enum. Each holds a `Backtrace`, an optional upstream cause, and helper methods + (`config_file(&self) -> &Path`). Keep any `ErrorKind` private and expose `is_io()` + style methods. Capture the backtrace in `new()` or `From`. `Display` prints a summary, + the backtrace, and the cause. Implement `std::error::Error`. Reuse one general error + across similar functions (`ParseError` for `parse_json` and `parse_toml`). +- **M-FROM-ERROR**: implement `From for Error` so `?` converts; `map_err` + only for foreign errors or to add context. +- **M-INIT-BUILDER**: up to two optional parameters use inherent constructors (`new`, + `with_a`, `with_b`, `with_a_b`). At four or more permutations, `FooBuilder` with + setters named after fields (`x()`, not `set_x()`), `build()`, and `Foo::builder()`. + `FooBuilder::new()` is not public. Required parameters arrive through + `deps: impl Into`. +- **M-INIT-CASCADED**: constructors with four or more parameters group them into semantic + types: `Deposit::new(account, amount)`. +- **M-SERVICES-CLONE**: heavyweight services implement cheap `Clone` through + `Arc`; clones share state. +- **M-ESSENTIAL-FN-INHERENT**: core functionality in inherent methods; trait impls + forward to them, so callers need no import. +- **M-BALANCED-MODULES**: essential items at the crate root; group the rest by use case + (`account`, `network`), not kind (`traits`, `errors`). +- **M-NO-PRELUDE**: no prelude or `use foo::*` target. Fix the module design instead. +- **M-PARAMETER-CONSISTENCY**: shared parameters in the same order everywhere. + Call-specific first, ubiquitous (`&logger`) last, closures last, at most one closure. +- **M-COLLECTION-TRAITS**: custom collections provide `Iter`, `IterMut`, `IntoIter`, + `iter()` / `iter_mut()`, `IntoIterator` for owned and borrowed, `FromIterator`, + `Extend`, `DoubleEndedIterator` / `ExactSizeIterator` where applicable. `size_hint()` + is truthful. +- **M-ASYNC-FN**: `async fn foo() -> Result` over `fn foo() -> impl Future`. The + explicit form only in traits or for hot functions (M-ASYNC-STACK-SIZE). + +## Libraries: resilience + +- **M-AVOID-STATICS**: avoid statics and thread-locals where a consistent value matters. + Two semver-incompatible copies of a crate get separate statics. +- **M-BUILD-RESULT**: builder setters are infallible; validation, including cross-field + checks, lives in `build() -> Result<_, _>`. +- **M-INTEGRATION-TESTS**: tests using only the public API go in `tests/`. Prefer an + integration test whenever either would do. +- **M-LOG-NOT-PRINT**: production code uses the telemetry framework, not `println!` / + `dbg!`. Only CLIs writing their UI to stdout are exempt. +- **M-MOCKABLE-SYSCALLS**: types doing file, network, clock, entropy, or other + non-deterministic I/O must be mockable. Provide `new_mocked() -> (Self, MockCtrl)` + behind `test-util`; don't offer a `Default` that performs I/O. +- **M-NO-GLOB-REEXPORTS**: re-export individually (`pub use foo::{A, B, C};`). Globs + only for platform HAL modules selected by `cfg(target_os)`. +- **M-STRONG-TYPES**: the strongest std type (`PathBuf` / `Path` for OS data). Plain + numbers stay plain at API boundaries; no `NonZero` or `Saturating` there. +- **M-STRONG-TYPES-GUARD**: a newtype encoding an invariant (month 1..=12) enforces it in + a fallible constructor returning `Result`. A panicking `const fn new` is allowed. No + infallible `From`; use `TryFrom` / `FromStr`. +- **M-TEST-UTIL**: mocks, sensitive-data inspection, safety overrides, and fake data + generators behind a single `test-util` feature. + +## Libraries: building + +- **M-OOBE**: non-platform crates build on all Tier 1 targets with only cargo and rustc, + no extra tools or environment variables. Code generation runs at publish time and its + output ships in the crate. +- **M-SYS-CRATES**: `-sys` crates build native code from `build.rs` with the `cc` crate, + embed verifiable upstream sources (URL plus hash), make optional tools optional, + pre-generate bindgen output, and support static and `libloading` dynamic linking. +- **M-FEATURES-ADDITIVE**: any combination of features compiles. Use a `std` feature, + never `no-std`. A feature never removes or changes a public item (adding + `#[non_exhaustive]` enum variants is fine). + +## Macros + +- **M-MACRO-LAST-RESORT**: macros only when the language can't do the job; they are + opaque, slow to compile, and brittle across editions. +- **M-EXAMPLE-OVER-PROC**: `macro_rules!` over proc macros when it suffices. +- **M-MACROS-DONT-LIE**: macros never change a type's kind, alter a function signature, + or add or remove `async`. +- **M-MACRO-MAIN-CRATE**: structure as `foo` (re-exports), `foo_proc` (facade), + `foo_proc_impl` (logic and tests). Don't support renamed imports. +- **M-MACRO-VERSION-PIN**: companion macro crates pinned with `=x.y.z` and published + together. +- **M-MACRO-HELPERS**: generated code reaches third-party items through a hidden + `#[doc(hidden)] pub mod _private { pub use ::bar::Bar; }`. +- **M-PROC-IMPL**: proc macro crate is a thin shim over a normal library crate holding + the logic and snapshot tests (`insta`); `trybuild` tests for error messages. +- **M-PROC-IMPLIED-ITEMS**: macros don't generate hidden or extra public types (except + Rocket-style function-plus-struct handlers). + +## Applications + +- **M-APP-ERROR**: applications and single-app crates may use `anyhow`, `eyre`, or + similar; libraries follow M-ERRORS-CANONICAL-STRUCTS. Don't mix several app-level + error types. +- **M-MIMALLOC-APPS**: applications set `#[global_allocator]` to `mimalloc` (up to 25% + gains reported). +- **M-TARGET-CPU**: server apps compile for the highest `target-cpu` the deployment + guarantees (`x86-64-v3` via `.cargo/config.toml`). Libraries ignore this. + +## FFI + +- **M-FFI-NAMING**: `-sys` crates import C libraries; `-ffi` crates export Rust as a + C-style library. +- **M-FFI-TRANSLATES**: business logic in a safe core crate; the `-ffi` crate only + translates types and signatures. No `repr(C)` pointer fields in core types. +- **M-ISOLATE-DLL-STATE**: across DLL boundaries share only portable data: `#[repr(C)]` + types with no statics, thread-locals, `TypeId`, or pointers to non-portable data. + +## Correctness + +- **M-UNSAFE**: `unsafe` only for a novel abstraction, a benchmarked performance need, or + FFI/platform calls. Banned: enum casts via `transmute`, `unsafe impl Send` to bypass + bounds, `transmute` to bypass lifetimes. Each use needs plain-text safety reasoning; + new abstractions are tested against adversarial code and pass Miri. +- **M-UNSAFE-IMPLIES-UB**: mark a function or trait `unsafe` only when misuse risks + undefined behavior, not for merely dangerous operations (`delete_database()`). +- **M-UNSOUND**: a safe function that can cause UB through any safe calls is unsound. + Unsound abstractions are never permissible. If you can't encapsulate it, expose an + `unsafe fn` and document the contract. Soundness boundaries are module boundaries. +- **M-PANIC-IS-STOP**: panics are not exceptions; a panic means the program should stop + now. Don't use panics to report errors or rely on them being caught. Valid: programming + errors (`expect("must never happen")`), const contexts, user-requested unwrap-style + methods, poisoned-lock `unwrap()`. Code must still be minimally panic-safe. +- **M-PANIC-ON-BUG**: detected bugs and contract violations panic, in libraries and + applications. Don't return an `Error` the caller can't act on. Fallible input returns + `Result` (`parse_uri(&str) -> Result`). Prefer types that make the bad + state unrepresentable. +- **M-PANIC-CONTINUATION**: `catch_unwind` is a last resort. Libraries don't catch and + continue. Servers may catch per request but should then promote a controlled restart. +- **M-PANIC-MESSAGE**: every intentional panic (`panic!`, `assert!`, `unreachable!`, + `todo!`) has a message with the relevant values: + `assert!(buf.len() >= HEADER_SIZE, "buffer too small: got {} bytes", buf.len())`. + +## Performance + +- **M-HOTPATH**: decide early whether the crate is performance-relevant; if so, find and + benchmark hot paths (criterion or divan), profile regularly, document hot spots. +- **M-THROUGHPUT**: optimize for items per CPU cycle; batched APIs; no hot spinning or + per-item work where batching is possible. +- **M-YIELD-POINTS**: long CPU-bound async work yields (`yield_now().await`) roughly + every 10 to 100 microseconds. +- **M-MEM-REUSE**: let callers own and reuse buffers: `get_in(id, &mut value)` alongside + a convenience `get(id)`; provide `clear()`. Arenas for deep call stacks. +- **M-LOG-OVERHEAD**: no telemetry in hot inner loops; no per-event `format!`. +- **M-AVOID-INDIRECTION**: don't stack `Arc` layers on hot types; lift hot cacheable + fields (`enabled: bool`) into the owning struct. +- **M-BOX-DST**: frequently created, immutable, non-user-visible sequences use + `Box<[T]>`, `Box`, or `Arc` instead of `Vec` / `String`. +- **M-SHRINK-TO-FIT**: `shrink_to_fit()` on long-lived growable collections built + without a reservation. +- **M-FAST-HASHER**: `foldhash` or `FxHash` for trusted internal keys; the default hasher + for untrusted input. +- **M-INITIAL-CAPACITY**: `with_capacity` when the size is known; `collect()` over push + loops. +- **M-ASYNC-STACK-SIZE**: track the size of hot futures with `size_of_val` in a test; + shrink state held across `.await`; move setup outside the async block. + +## Project + +- **M-CARGO-WORKSPACE**: share metadata, versions, and lints through + `[workspace.dependencies]` and `[workspace.lints]`, with `default-features = false` + on workspace dependency definitions. +- **M-CRATES-FLAT-FOLDER**: one workspace `Cargo.toml`, crates as siblings under + `crates/`, never nested inside another crate or its `src/`. +- **M-CRATES-IN-WORKSPACE**: every crate is a workspace member; siblings referenced as + `sibling.workspace = true`. +- **M-LATEST-EDITION**: new crates use the latest stable edition (2024 or later). +- **M-MSRV**: set a minimum supported Rust version at creation; raise it conservatively + in minor releases. + +## Documentation + +- **M-CANONICAL-DOCS**: public items get a one-line summary, extended docs, then + `# Examples`, `# Errors`, `# Panics`, `# Safety` (required for `unsafe fn`), `# Abort` + as applicable. Parameters described in prose, not a table. +- **M-DOC-INLINE**: `#[doc(inline)]` on `pub use` of crate-internal items; not for std or + third-party types. +- **M-FIRST-DOC-SENTENCE**: first sentence on one line, about 15 words; it becomes the + module summary. +- **M-MODULE-DOCS**: every public module has `//!` docs: what it contains, when to use + it, examples, observable side effects. + +## AI (agent-specific) + +- **M-DESIGN-FOR-AI**: what makes an API easy for humans makes it easy for agents: + idiomatic design, thorough docs on every module and public item, directly usable + examples, strong types, APIs testable through fakes or mocks, good coverage of + observable behavior. The compiler's checks counterbalance an agent's limited + understanding. +- **M-NO-META-DESIGN-DOCUMENTATION**: no design journals, "why we picked X" essays, or + agent self-report tables (a `Rule | Applied | Where` list) in crate or module docs. + Document the end state. A README section on enduring architectural goals is fine. +- **M-RUST-SHAPED**: when porting from C#, Java, or C++, don't translate constructs + one-to-one. Keep the domain logic; use Rust idioms for errors, tasks, ownership, and + traits. A `throw_if_null()` signals a problem. +- **M-SINGLE-ITEM-PATH**: one path per public item. Don't combine + `pub mod db { pub struct Connection; }` with `pub use db::Connection;`. Agents tend to + add re-exports during refactors instead of redesigning. A `pub(crate) mod` with a + single `pub use` is fine. +- **M-TAUTOLOGICAL-TESTS**: don't write tests that restate constants or mirror + implementation branches (`assert_eq!(CHECKPOINTS, [0, 90, 180, 270])`). Test + properties: even spacing, monotonicity, round-trips. diff --git a/skills/visioncraft/references/rust/sources/rust-api-guidelines.md b/skills/visioncraft/references/rust/sources/rust-api-guidelines.md new file mode 100644 index 0000000..72c9277 --- /dev/null +++ b/skills/visioncraft/references/rust/sources/rust-api-guidelines.md @@ -0,0 +1,214 @@ +# Rust API Guidelines (digest) + +Source: https://rust-lang.github.io/api-guidelines/ (official rust-lang project). +Read this when designing or reviewing a public API or publishing a crate. All 54 +checklist items are covered, grouped as in the original. + +## Naming + +- **C-CASE**: `UpperCamelCase` for types, traits, enum variants; `snake_case` for + modules, functions, methods, locals; `SCREAMING_SNAKE_CASE` for consts and statics; + short type params (`T`); short lowercase lifetimes (`'a`, `'de`). An acronym is one word + in `UpperCamelCase` (`Uuid`, `Stdin`) and lowercased in `snake_case` (`is_xid_start`). + Crate names never carry a `-rs` or `-rust` affix. +- **C-CONV**: ad-hoc conversion prefixes: + + | Prefix | Cost | Ownership | + |---|---|---| + | `as_` | free | borrowed -> borrowed | + | `to_` | expensive | borrowed -> borrowed; borrowed -> owned (non-Copy); owned -> owned (Copy) | + | `into_` | variable | owned -> owned (non-Copy) | + + `as_` and `into_` expose the representation; `to_` stays at the same abstraction level + but does work (`Path::to_str` checks UTF-8). Wrappers expose their value with + `into_inner()`. `mut` goes in type order: `as_mut_slice`. +- **C-GETTER**: no `get_` prefix: `first(&self) -> &First`, `first_mut(&mut self)`. Bare + `get` only when there is one obvious thing to get (`Cell::get`). Checked accessors get + `unsafe fn get_unchecked` siblings. +- **C-ITER**: collections provide `iter(&self) -> Iter` (items `&U`), `iter_mut`, and + `into_iter(self) -> IntoIter`. Non-homogeneous types (`str`) use `bytes()`, `chars()`. +- **C-ITER-TY**: the iterator type is named after the method: `into_iter` -> `IntoIter`, + `keys` -> `Keys`, `percent_encode` -> `PercentEncode`. +- **C-FEATURE**: feature names have no placeholder words: `abc`, not `use-abc`. Gate std + as `default = ["std"]`, `std = []`, with `#![no_std]` and + `#[cfg(feature = "std")] extern crate std;`. Features are additive, so `no-abc` is + almost always wrong. +- **C-WORD-ORDER**: be consistent with std: error types are verb-object-error + (`ParseBoolError`, so `ParseAddrError`, not `AddrParseError`). + +## Interoperability + +- **C-COMMON-TRAITS**: eagerly implement `Copy`, `Clone`, `Eq`, `PartialEq`, `Ord`, + `PartialOrd`, `Hash`, `Debug`, `Display`, `Default` where applicable. Orphan rules mean + downstream crates cannot add them. Provide an empty `new()` alongside `Default`, and + make them behave identically. +- **C-CONV-TRAITS**: implement `From`, `TryFrom`, `AsRef`, `AsMut`. Never implement + `Into` or `TryInto` directly. `From for u32` for lossless, `TryFrom for u16` + for fallible; never `From for u16`. +- **C-COLLECT**: collections implement `FromIterator` and `Extend` so `collect`, + `partition`, and `unzip` work. +- **C-SERDE**: data-structure types implement `Serialize` / `Deserialize` behind an + optional feature named exactly `serde`: + `#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]`. +- **C-SEND-SYNC**: `Send` and `Sync` are automatic; check them on types holding raw + pointers and lock them in with a test: `fn assert_send() {}` then + `assert_send::();`. +- **C-GOOD-ERR**: any `E` in a public `Result` implements `std::error::Error` and + should be `Send + Sync`. Boxed errors are `Box` + (`'static` enables `downcast_ref`). Never use `()` as an error type. `Display` messages + are lowercase, concise, no trailing punctuation. Don't implement the deprecated + `description()`. +- **C-NUM-FMT**: number-like types you would combine with `|` or `&` (bitflags) + implement `LowerHex`, `UpperHex`, `Octal`, `Binary`. Quantities (`Nanoseconds(u64)`) + don't need them. +- **C-RW-VALUE**: generic functions take `R: Read` and `W: Write` by value; `&mut R` + also implements `Read`, so callers pass `&mut f` to keep using it. Say so in the docs. + +## Macros + +- **C-EVOCATIVE**: macro input resembles the output (`struct S: u32 { .. }`, const-like + items end in `;`). +- **C-MACRO-ATTR**: macros that emit items accept attributes on each item, so + `#[cfg(..)]` and `#[derive(..)]` work. +- **C-ANYWHERE**: item macros work at module and function scope; test both. Emitting + `super::U` breaks inside a function. +- **C-MACRO-VIS**: emitted items are private unless the input says `pub`. +- **C-MACRO-TY**: a `$t:ty` fragment accepts primitives, relative and absolute paths, + `super::`, and generics. Don't emit a nested `pub mod` that can't see local types. + +## Documentation + +- **C-CRATE-DOC**: crate-level docs are thorough and include examples. +- **C-EXAMPLE**: every public module, trait, struct, enum, function, method, macro, and + type alias has an example, within reason. Show why to use it, not mechanically how. +- **C-QUESTION-MARK**: examples use `?`, never `try!` or `unwrap()`, because users copy + them verbatim. Hide the scaffolding with `#` lines: + + ```rust + /// ``` + /// # use std::error::Error; + /// # fn main() -> Result<(), Box> { + /// let value = parse_it("...")?; + /// # Ok(()) + /// # } + /// ``` + ``` + +- **C-FAILURE**: `# Errors` when `Err` can be returned (including trait methods whose + impls may err); `# Panics` when a function can panic; `# Safety` on every `unsafe fn` + listing every caller invariant. +- **C-LINK**: link items in prose with `` [`Type`] ``. +- **C-METADATA**: `[package]` has `authors`, `description`, `license`, `repository`, + `keywords`, `categories`; `documentation` only if not on docs.rs; `homepage` only if + distinct from `repository`. +- **C-RELNOTES**: keep release notes, mark breaking changes, and tag releases with + annotated tags (`git tag -a`). +- **C-HIDDEN**: `#[doc(hidden)]` on impls users never trigger + (`From for PublicError` exists only to enable `?`). Use `pub(crate)` for + internals. + +## Predictability + +- **C-SMART-PTR**: smart pointers add no inherent methods; use associated functions + (`Box::into_raw(b)`, not `b.into_raw()`), so a call can't be ambiguous with the pointee. +- **C-CONV-SPECIFIC**: put conversions on the more specific type (`str::as_bytes`, + `str::from_utf8`). Prefer `to_` / `as_` / `into_` over `from_`; they chain better. +- **C-METHOD**: if a function has a clear receiver, make it a method + (`impl Foo { fn frob(&self, w: Widget) }`). Methods need no import, autoborrow, and + express ownership through `self`. +- **C-NO-OUT**: return multiple values as a tuple or struct, not `&mut` out-parameters. + Exception: reusing a caller-owned buffer (`Read::read`). +- **C-OVERLOAD**: implement `std::ops` traits only when the operation resembles the + operator and shares its properties (`Mul` should be associative). +- **C-DEREF**: only smart pointers implement `Deref` / `DerefMut`. The coercion and + method-resolution rules are designed for them (`Box`, `String`, `Rc`, `Arc`, `Cow`). +- **C-CTOR**: constructors are static inherent methods. Primary is `new()`; secondary + ones take a `_with_foo` suffix (`open_with_offset`); I/O resources use domain names + (`File::open`, `TcpStream::connect`); conversion constructors are `from_foo` and may be + `unsafe` (`Box::from_raw`) or take extra args (`u64::from_str_radix`), unlike `From`. + Many options means a builder. + +## Flexibility + +- **C-INTERMEDIATE**: expose work already done. `binary_search` reports the insertion + index on a miss; `String::from_utf8`'s error returns the valid prefix length and the + bytes; `HashMap::insert` returns the old value. +- **C-CALLER-CONTROL**: if the function needs ownership, take by value and never clone a + borrow internally. If it only reads or mutates, take `&` / `&mut`. Bound by `Copy` only + when required, not to advertise cheapness. +- **C-GENERIC**: assume as little as possible. Iterating only? + `fn foo>(iter: I)`, not `&[i64]`. `File::open` takes + `AsRef`. Costs: code size, one concrete type per parameter, verbose signatures. +- **C-OBJECT**: decide early whether a trait is a bound or an object. Generic methods and + `Self` outside the receiver block object safety; exclude them with `where Self: Sized`: + + ```rust + trait MyTrait { + fn object_safe(&self, i: i32); + fn not_object_safe(&self, t: T) where Self: Sized; + } + ``` + +## Type safety + +- **C-NEWTYPE**: `struct Miles(pub f64)` vs `struct Kilometers(pub f64)` gives static + distinctions at zero runtime cost. (The guide cites the Mars Climate Orbiter.) +- **C-CUSTOM-TYPE**: don't pass `bool`, `u8`, or `Option` where meaning is ambiguous. + `Widget::new(Small, Round)`, not `Widget::new(true, false)`. Enums can also grow later. +- **C-BITFLAG**: independent flags use the `bitflags` crate; an enum models exactly one + choice. Explicit discriminants suit serialization or C interop. +- **C-BUILDER**: introduce `TBuilder` when a type has many inputs, compound data, optional + config, several flavors, or side effects on build. The constructor takes only required + data, config methods chain, terminal methods build. Prefer non-consuming builders + (`&mut self -> &mut Self`, terminal `&self`): `Command::new("cat").arg("f").spawn()`. + Consuming builders only when the terminal method must move a value out. + +## Dependability + +- **C-VALIDATE**: enforce validity, in preference order: statically (a type that rules + out bad input, `fn foo(a: Ascii)` over `fn foo(a: u8)`), dynamically (check as you + process, `debug_assert!` for expensive checks), opt-out (`_unchecked` siblings or a + `raw` module for confident callers). +- **C-DTOR-FAIL**: destructors never fail; failing during unwinding aborts. Provide + `close(self) -> Result<..>` and let `Drop` be best-effort. +- **C-DTOR-BLOCK**: destructors don't block. Offer a separate method that prepares an + infallible, non-blocking teardown. + +## Debuggability + +- **C-DEBUG**: all public types implement `Debug`. Exceptions are rare. +- **C-DEBUG-NONEMPTY**: even empty values produce non-empty `Debug` output + (`""` -> `"\"\""`, empty vec -> `"[]"`). + +## Future proofing + +- **C-SEALED**: the sealed trait pattern lets you add methods without breaking users: + + ```rust + pub trait TheTrait: private::Sealed { /* ... */ } + impl TheTrait for usize { /* ... */ } + mod private { + pub trait Sealed {} + impl Sealed for usize {} + } + ``` + + Document that the trait is sealed. +- **C-STRUCT-PRIVATE**: fields private by default; a public field fixes the + representation and blocks invariants. Public fields only for passive C-style data. +- **C-NEWTYPE-HIDE**: hide implementation types behind a newtype + (`pub struct MyIter(Enumerate>)`) so the inner type can change. `impl Trait` + is more concise but awkward for `Debug` / `Clone` bounds; fine for internal APIs. +- **C-STRUCT-BOUNDS**: no derivable bounds on struct definitions. + `#[derive(Clone, Debug, PartialEq)] struct Good`, not + `struct Bad`. Never bound a data structure by `Clone`, + `PartialEq`, `PartialOrd`, `Debug`, `Display`, `Default`, `Error`, `Serialize`, + `Deserialize`. Exceptions: associated-type references, `?Sized`, a `Drop` impl that + needs the bound. + +## Necessities + +- **C-STABLE**: a 1.0+ crate needs every public dependency (any crate whose types appear + in its API) to be stable too. `From` leaks `other_crate`. +- **C-PERMISSIVE**: `license = "MIT OR Apache-2.0"` with both license files, matching + Rust itself. Depend only on permissively licensed crates. diff --git a/skills/visioncraft/references/rust/sources/rust-design-patterns.md b/skills/visioncraft/references/rust/sources/rust-design-patterns.md new file mode 100644 index 0000000..e92dfa3 --- /dev/null +++ b/skills/visioncraft/references/rust/sources/rust-design-patterns.md @@ -0,0 +1,184 @@ +# Rust Design Patterns (digest) + +Source: https://rust-unofficial.github.io/patterns/ (community book, last updated +September 2026). Idioms, design patterns, and anti-patterns with code. Read this when you +need a concrete pattern (builder, RAII guard, newtype, visitor, `mem::take`) or want to +check whether something is a known anti-pattern. + +## Idioms + +**Borrowed types for arguments.** Take `&str`, `&[T]`, `&T` instead of `&String`, +`&Vec`, `&Box`. Callers can then pass owned values, borrows, or literals through +deref coercion, and you avoid a layer of indirection. + +```rust +fn three_vowels(word: &str) -> bool { /* ... */ } +three_vowels(&String::from("Ferris")); // &String coerces to &str +three_vowels("Curious"); // literal works too +``` + +**Concatenate strings with `format!`.** `format!("Hello {name}!")` is the most readable +way to mix literals and variables. A pre-allocated `String` with `push_str` is faster +in hot paths. + +**Constructors.** Provide an associated function `new` with no `self`, even when it takes +no arguments and duplicates `Default`. + +**The `Default` trait.** `#[derive(Default)]` when every field implements it; struct +update syntax for partial configuration: + +```rust +let conf = MyConfiguration { check: true, ..Default::default() }; +``` + +Only one `Default` per type; use named constructors for other starting states. + +**Collections are smart pointers.** An owning collection implements `Deref` to its +borrowed view (`Vec` -> `[T]`, `String` -> `str`) so the view's methods are available +on the owner. Methods reached through `Deref` don't count toward trait bounds, so generic +code may need `Borrow` or `AsRef`. + +**Finalisation in destructors.** Rust has no `finally`; put cleanup in a `Drop` impl on a +guard bound to a named variable (`let _exit = Guard;`). It runs on early `?` returns and +on unwinding. `let _ = ..` drops immediately. Destructors can be skipped by an abort, an +infinite loop, or a panic during unwinding, so don't rely on them for essential work. + +**`mem::take` and `mem::replace`.** Move a field out of a `&mut` value by swapping in a +placeholder instead of cloning. `take` uses `Default` (an empty `String` doesn't +allocate); `replace` takes an explicit value; `Option::take` for options. + +```rust +fn a_to_b(e: &mut MyEnum) { + if let MyEnum::A { name, x: 0 } = e { + *e = MyEnum::B { name: mem::take(name) }; + } +} +``` + +**On-stack dynamic dispatch.** Get `dyn Trait` over differently typed values without +`Box` by binding a reference in an `if` expression (temporary lifetime extension since +Rust 1.79): + +```rust +let readable: &mut dyn io::Read = if arg == "-" { + &mut io::stdin() +} else { + &mut fs::File::open(arg)? +}; +``` + +**Iterating over an `Option`.** `Option` is an iterator of zero or one items: +`vec.extend(opt)`, `iter.chain(opt.iter())`. `std::iter::once` when always `Some`. For a +plain branch, `if let Some(..)` reads better. + +**Pass variables to closure.** When a closure needs some captures cloned or borrowed and +others moved, rebind them in an inner block, then `move`: + +```rust +let closure = { + let num2 = num2.clone(); // cloned + let num3 = num3.as_ref(); // borrowed + move || *num1 + *num2 + *num3 // num1 moved +}; +``` + +**`#[non_exhaustive]` and private fields.** In a library, mark public structs, enums, or +variants `#[non_exhaustive]` when you may add fields or variants later. Within a crate, +a private `_b: ()` field blocks struct literals. Use sparingly: it forces wildcard arms +downstream, and a major-version bump is often better. + +**Easy doc initialization.** When a doc example needs lots of setup, wrap the example in +a hidden helper function (`# fn call_send(conn: Connection) {`) that takes the prepared +values as parameters. The example compiles but doesn't run its assertions. + +**Temporary mutability.** Finish mutation in setup, then freeze: `let data = data;`. + +**Return consumed argument on error.** A fallible function that takes ownership returns +the argument inside the error so the caller can retry without cloning +(`String::from_utf8` and `FromUtf8Error::into_bytes`). + +## Design patterns + +The section opens with YAGNI: many classic patterns are unnecessary in Rust. Strategy is +just traits; Option::map is already strategy. + +### Behavioural + +**Command.** Store actions as values: `Box` for command structs with several +methods (`execute` / `rollback`), `fn()` pointers for simple actions, `Fn` closures for +captured state. Function pointers and closures avoid dynamic dispatch. + +**Interpreter.** When a recurring problem is a small language, define a grammar and an +interpreter. For lightweight DSL syntax, `macro_rules!`. + +**Newtype.** A single-field tuple struct creates a distinct type (`Miles` vs +`Kilometres`), hides secrets (a `Password(String)` whose `Display` prints `****`), or +restricts the trait set. No runtime cost; the cost is forwarding boilerplate +(`derive_more` helps). + +**RAII with guards.** Acquire in a constructor, release in `Drop`, and expose the resource +only through a guard that implements `Deref` (as `MutexGuard` does). The borrow checker +stops references obtained through the guard from outliving it. + +**Strategy.** Interchangeable algorithms as a trait with a generic bound for static +dispatch; for small variations, a closure bound (`F: Fn(u8, u8) -> u8`) is enough. + +**Visitor.** Run several algorithms over heterogeneous data (an AST) without modifying +it: a `Visitor` trait with one `visit_*` method per node type, plus shared `walk_*` +traversal helpers. For homogeneous data, use iterators. + +### Creational + +**Builder.** `Foo::builder()` returns `FooBuilder` with chained setters and `build()`. +Avoids constructor proliferation and lets you add fields without breaking callers. +Setters that take `&mut self` are often more ergonomic than by-value. `derive_builder` +removes the boilerplate. + +**Fold.** Map a tree into a new tree with a `Folder` trait whose default `fold_*` methods +recurse into children; override only the nodes you change. (Not `Iterator::fold`.) + +### Structural + +**Prefer small crates.** Single-purpose crates compose, build in parallel, and get +reused. Costs: dependency hell (two `url` versions give incompatible `Url` types), no +curation on crates.io, less cross-crate LTO. + +**Contain unsafety in small modules.** Put `unsafe` in the smallest module that can +uphold its invariants and wrap it in a safe interface. `String` is a `Vec` whose safe +methods maintain the UTF-8 invariant. + +**Compose structs.** When one large struct causes borrow conflicts, split it into +smaller structs and compose them in the parent; each piece can then be borrowed +separately, and the design usually improves. + +## Anti-patterns + +**Clone to satisfy the borrow checker.** A `.clone()` added only to make a borrow error +go away creates a separate copy whose later changes aren't reflected in the original. +`Rc` / `Arc` clones are cheap and fine. Clones are acceptable in prototypes, but should +be deliberate; fix the ownership design or use `mem::take` / `replace`. Clippy flags +unnecessary clones. + +**`#![deny(warnings)]`.** New compiler releases add lints that start as warnings, so the +build breaks after a toolchain update, and it blocks extra lint tools. Use +`RUSTFLAGS="-D warnings"` in CI or deny specific lints by name. + +**Deref polymorphism.** Implementing `Deref` on `Derived` to inherit +methods is surprising: no subtyping, `Base`'s traits don't carry over in bounds, `self` +semantics differ, and the implicit mechanism misleads readers. `Deref` is for smart +pointers. Write explicit forwarding methods, define a trait, or use a delegation crate +(`delegate`, `ambassador`). + +## Functional programming + +**Paradigms.** Imperative says how; declarative says what. Prefer iterator combinators +to mutable accumulation loops: `(1..11).fold(0, |a, b| a + b)`. + +**Generics as type classes.** Each generic argument produces a distinct type, so encode +protocol or state in a type parameter and invalid calls fail to compile: +`impl FileDownloadRequest { fn mount_point(&self) -> &Path }` doesn't exist for the +BOOTP variant. Alternatives: builder for construction-time splits, strategy when only +behavior varies. Cost: larger binary. + +**Functional optics.** Iso, Poly Iso, and Prism, illustrated through Serde's Visitor API. +Rarely used directly in Rust; useful mainly for reading APIs such as Serde. diff --git a/skills/visioncraft/references/rust/steering.md b/skills/visioncraft/references/rust/steering.md new file mode 100644 index 0000000..5377770 --- /dev/null +++ b/skills/visioncraft/references/rust/steering.md @@ -0,0 +1,557 @@ +# Rust steering + +The thirteen language sections below retain the BeautifulRust guidance credited +in [NOTICE.md](NOTICE.md), with its five [source digests](sources/). VisionCraft's +portable scope rules replace the former estate overlay. Project requirements +and supported toolchains take precedence over generic style preferences. + +Use [review.md](review.md) for a scoped review and [port.md](port.md) for a port. +Load source digests only when their detail helps the current decision. Their +upstream claims are pinned reference material, not a new verification of those +external projects. + +## 0. Scope, execution and publication + +- Use maintained cryptographic implementations and established formats. Verify + relevant published vectors rather than transliterating a bespoke primitive. + Repair the security boundary within the authorised task; do not expand an + unrelated edit into an unbounded cryptography rewrite. +- Run the repository's supported feature/target matrix. `--all-features` is not + automatically appropriate when features require hardware or external SDKs. + Report omitted combinations; do not replace real dependencies with stubs to + obtain a green authentication or persistence test. +- Set the actual Cargo `rust-version` when maintaining an MSRV. Opt-in lint + assets must be compatible with that toolchain; rules requiring a newer MSRV + need deliberate adoption, not a silently inert metadata entry. +- Before publishing a reusable crate, supply crate/public-item documentation, + meaningful compiling examples, README, licences and repository metadata. + Run the relevant tests and warning-free documentation build. Publication, + registry consumption and deployed use need separate observations. +- Describe gates as executed only after reading their actual results. After + repeated unsuccessful repairs, reconsider the cause. The [debugging guide](../debugging.md) + and [diagram diagnosis](../diagram-diagnosis.md) provide the deeper path. +- These sections are a review rubric, not a demand for every possible tool on + every edit. Scope tests and lint changes to meaningful risk; preserve existing + compatibility and explain deliberate exceptions. + +## Contents + +1. [Mindset](#1-mindset) +2. [Before you hand back code](#2-before-you-hand-back-code) +3. [Ownership and borrowing](#3-ownership-and-borrowing) +4. [Types and API design](#4-types-and-api-design) +5. [Errors and panics](#5-errors-and-panics) +6. [Everyday idioms](#6-everyday-idioms) +7. [Concurrency and async](#7-concurrency-and-async) +8. [Unsafe and FFI](#8-unsafe-and-ffi) +9. [Crates, modules, dependencies](#9-crates-modules-dependencies) +10. [Documentation and comments](#10-documentation-and-comments) +11. [Tests](#11-tests) +12. [Performance](#12-performance-in-order) +13. [Final checklist](#13-final-checklist) + +## 1. Mindset + +- **Write Rust-shaped code.** Don't port C++, Java, C#, or Python constructs one-to-one. + Model errors with `Result`, resources with ownership and `Drop`, polymorphism with + traits and enums, and nullability with `Option`. Inheritance-flavored tricks (`Deref` to + a "base" struct, `Manager`/`Factory` types, `throw_if_null` helpers) are smells. +- **Make invalid states unrepresentable.** Push invariants into types: enums instead of + bool flags and "must be X if Y" comments, newtypes for units and IDs, fallible + constructors that validate once. Then the compiler enforces what a comment only requests. +- **Application code is not library code.** Library code (anything with external users) + follows the API-design rules below strictly. Application code should favor simplicity + and directness: concrete types, `String` or `&str` rather than `impl Into` + parameters, `anyhow`-style errors, `Vec` return values, no speculative generality. +- **Let the tools do the work.** rustfmt owns formatting, clippy owns idiom checks, the + compiler owns memory safety. Spend your attention on design. + +## 2. Before you hand back code + +Run these and fix everything they report: + +```bash +cargo fmt +cargo clippy --all-targets -- -D warnings # add --features per section 0 +cargo test +cargo doc --no-deps # libraries: catches broken doc links and missing docs +``` + +- Fix a lint rather than silencing it. When a lint is genuinely wrong for one item, use + `#[expect(clippy::name, reason = "...")]` on the narrowest item. `expect` warns when + the lint stops firing, so stale suppressions get cleaned up. Use `#[allow]` only in + generated code or macro output. +- Never put `#![deny(warnings)]` in source: new toolchains add warnings and break the + build. Enforce warnings-as-errors in CI instead, with `cargo clippy -- -D warnings`. +- Configure lints once in `Cargo.toml` (`[lints]` or `[workspace.lints]`), not with + scattered crate attributes. If a project has none, or has an empty `[lints]` table, + suggest [lints/lints.toml](./lints/lints.toml) and [lints/clippy.toml](./lints/clippy.toml); + the suppression lints in it need `rust-version` 1.81 or later (section 0). + +## 3. Ownership and borrowing + +**Prefer unique ownership.** Reach for `Rc`/`Arc` only when shared ownership is part of +the design, and for `RefCell`/`Mutex` only when interior mutability is. They are not +failures, but they move checking from compile time to run time, so use them on purpose. + +**Don't clone to make the borrow checker stop complaining.** A clone that exists only to +end a borrow produces a silent copy whose later changes are lost. Try these first, in +roughly this order: + +1. Extend a temporary with a named `let`, or shorten a borrow with a block. +2. Split a long expression into typed intermediates so the failing step is visible. +3. Move a field out of `&mut self` with `std::mem::take` (needs `Default`), + `std::mem::replace`, or `Option::take` instead of cloning it. +4. Split a large struct into smaller ones so disjoint fields can be borrowed separately. + The compiler tracks disjoint field borrows inside one function, but not across + method calls. +5. Clone small, immutable data deliberately, and say so in a comment if it's not obvious. +6. Use indices into an owning `Vec`, or `Rc>` with `Weak` back-pointers, as + a last resort. Avoid self-referential structs. + +```rust +// Move out of a &mut enum without cloning. +fn a_to_b(e: &mut MyEnum) { + if let MyEnum::A { name, x: 0 } = e { + *e = MyEnum::B { name: std::mem::take(name) }; + } +} +``` + +**Accept the most general borrowed type.** `&str` not `&String`, `&[T]` not `&Vec`, +`&T` not `&Box`, `Option<&T>` not `&Option`. Deref coercion then lets callers pass +owned values, borrows, or literals. Where you only read a path, string, or byte buffer, +`impl AsRef` / `impl AsRef` / `impl AsRef<[u8]>` is fine on parameters (never +on struct fields; store `PathBuf` and `String`). Library code that only iterates should +take `impl IntoIterator`; application code may simply take `&[T]`. + +**Take ownership only when you need it, and then take it by value.** If a function stores +or consumes its argument, take `T`, not `&T` plus an internal `.clone()`. If it only +reads, take `&T`; if it mutates in place, `&mut T`. Return multiple values as a tuple or +struct, not through `&mut` out-parameters (reusing a caller-owned buffer, as +`Read::read` does, is the exception). + +**Prefer owned data in structs.** A struct holding `&'a T` forces a lifetime onto every +container. Owning a `String` or `Vec` is usually simpler and rarely the bottleneck. +When a type does carry a lifetime, give it a descriptive name (`'src`, `'conn`); `'_` and +`'a` are fine on simple functions. + +**Freeze after setup.** Build with `let mut`, then rebind `let data = data;` so later +code cannot mutate it by accident. + +**Keep `Rc`, `Arc`, `Box`, and `RefCell` out of public signatures.** Take `&T`, +`&mut T`, or `T` and let callers decide how to own things. A service that must be shared +implements a cheap `Clone` by wrapping its state in `Arc` internally. + +## 4. Types and API design + +### Naming + +| Item | Case | Notes | +|---|---|---| +| Types, traits, enum variants | `UpperCamelCase` | Acronyms are one word: `Uuid`, `HttpClient` | +| Functions, methods, modules, locals | `snake_case` | | +| Constants, statics | `SCREAMING_SNAKE_CASE` | | +| Type parameters | short, from the main bound | `T`, `R: Read`, `W: Write` | +| Lifetimes | short lowercase | descriptive when on a type | + +- No `get_` prefix on getters: `fn len(&self)`, `fn name(&self) -> &str`, + `fn name_mut(&mut self)`. Use bare `get` only when there is one obvious thing to get + (`Cell::get`). Related: `set_foo(T)`, `take_foo()`, `with_foo(|f| ..)` for closure + access, and unsafe `_unchecked` siblings for checked accessors. +- Conversion prefixes signal cost and ownership: `as_` (free, borrow to borrow), `to_` + (expensive, borrow to owned or borrow to borrow), `into_` (consumes `self`). Put `mut` + in type order: `as_mut_slice`, not `as_slice_mut`. +- Constructors: `new` (primary), `with_capacity` / `new_with_foo` (variants), `try_new` + (fallible), `from_foo` (conversion; pair important ones with a `From` impl). I/O + resources use domain verbs: `File::open`, `TcpStream::connect`. +- `iter` / `iter_mut` / `into_iter` return types named `Iter` / `IterMut` / `IntoIter`; + `keys()` returns `Keys`. +- Error types read verb-object-error: `ParseBoolError`, not `BoolParseError`. +- Avoid weasel suffixes `Service`, `Manager`, `Factory`, `Helper`, `Util`. Name the thing + it is (`Bookings`, `Dispatcher`, `FooBuilder`). Don't repeat the module name in the + type (`foo::Id`, not `foo::FooId`). Avoid abbreviations an outsider wouldn't know. +- If you implement `len()`, implement `is_empty()`. +- Feature names are bare: `std`, `serde`, `alloc`, never `use-std` or `no-std`. + +### Model the domain with types + +- **Newtypes** for semantic distinctions: `struct Miles(f64)` and `struct Kilometers(f64)` + cannot be mixed, where a type alias can. Add `#[repr(transparent)]` when layout matters, + and derive or forward the traits you need (`derive_more` cuts the boilerplate). A + newtype that encodes an invariant (`Month`) validates in a fallible constructor + (`TryFrom`, `FromStr`, `try_new`) and never offers an infallible `From` from the raw type. +- **No `bool` parameters in public or shared signatures.** `report(true)` is unreadable at + the call site and cannot grow a third mode. Use a two-variant enum + (`Verbosity::Summary`, `Verbosity::Full`) or two methods (`report()`, + `report_verbose()`): `Widget::new(Size::Small, Shape::Round)`, not + `Widget::new(true, false)`. The only exception is a private helper whose call sites sit + a few lines away. When refactoring, an existing `bool` parameter is one of the smells to + remove, not a detail to preserve. +- **Named fields over tuples**, except single-field newtypes and very local code. +- **`Option` for absence, never sentinels** such as `-1` or `""`. **Data-carrying enums** + instead of "field X is only meaningful when Y is set". +- **Use the strongest std type:** `PathBuf` / `&Path` for paths, `Duration` for spans, + `NonZeroU32` internally only (keep plain integers at API boundaries). +- **Independent flags** use the `bitflags` crate; an enum models exactly one choice. + +### Derive and implement the standard traits eagerly + +Downstream crates cannot add std traits to your types (orphan rule), so you must. Derive +whenever every field supports it: `Debug` (on every public type; hand-write it to redact +secrets), `Clone` (except unique resources and key material), `Copy` (only small +bitwise-copyable types, because the compiler copies silently), `PartialEq` / `Eq`, +`PartialOrd` / `Ord` (never ship `PartialOrd` without `Ord` when a total order exists), +`Hash` (consistent with `Eq`), `Default`. Implement `Display` for anything meant to be +read: error types, string-like wrappers. Add `#[must_use]` to pure functions and to +types, such as errors and lazy values, whose discarding is a bug. + +Implement `From` / `TryFrom`, never `Into` / `TryInto` directly (blanket impls give you +those). Prefer `from` / `into` over `as`, which silently allows lossy casts. Implement +`FromStr` rather than an ad-hoc `from_str` method, `FromIterator` and `Extend` on +collections, and `IntoIterator` for both owned and borrowed forms. Implement `Deref` only +on smart pointers and owning collections (`Vec` to `[T]`), never to fake inheritance. +Overload operators only for their mathematical meaning. + +Don't put derivable trait bounds on struct definitions: `#[derive(Clone)] struct Good`, +not `struct Bad`. Bounds belong on the `impl` blocks that need them. + +If you hand-write `Ord`, hand-write `PartialEq`, `PartialOrd`, and `Hash` to agree with it +(compare the same fields, ignore the same fields). A derived `PartialEq` next to a custom +`Ord` breaks the std contract and misbehaves in `BTreeMap` and `sort`/`dedup`. Say in the +docs which fields equality ignores. + +### Constructors, builders, defaults + +- Provide `new()` even when `Default` exists, and make them agree (one delegates to the + other). Derive or implement `Default` so callers can write `..Default::default()`; + bag-of-options structs with public fields should always have it. +- Up to two optional parameters: inherent constructors (`new`, `with_a`, `with_b`). + Beyond that, or when construction validates or has side effects, add a builder: + `Foo::builder()` returns `FooBuilder`, setters are named after fields (`timeout(d)`, + not `set_timeout`) and infallible, and `build() -> Result` does all + validation including cross-field checks. Prefer non-consuming setters + (`&mut self -> &mut Self`) unless `build` must move a value out. +- A constructor with four or more loose arguments should group them into semantic types: + `Deposit::new(account, amount)` rather than four `&str` / `u64` parameters. + +### Visibility and evolution + +- Private by default. Fields stay private unless the struct is passive C-style data. + Widen to `pub(crate)` or `pub(super)` before `pub`. Making an item more public later is + non-breaking; the reverse is breaking, and every `pub` item is a promise. +- Mark public enums and public-field structs that cross crate boundaries + `#[non_exhaustive]` unless the set is a stable ontology. When matching one, list the + variants you handle and add a wildcard arm. +- Seal traits you don't want implemented downstream, and say so in the docs: + + ```rust + pub trait TheTrait: private::Sealed { /* ... */ } + mod private { + pub trait Sealed {} + impl Sealed for usize {} + } + ``` + +- Library code returns iterators, not a `Vec` collected only to return, behind `impl + Iterator` (internal APIs) or a newtype (public APIs you must keep stable). +- Expose each public item at exactly one path. Don't `pub use` a foreign crate's items + unless you are an umbrella crate. Avoid leaking third-party types into your public API; + feature-gate `serde` impls behind a feature named `serde`. If a dependency's type must + appear, re-export it so callers can name the matching version. +- Mark a function `const` only if it will stay `const`. Don't expose `ErrorKind` enums + or other internals that lock in failure modes you consider private. + +### Traits and generics + +- Define a trait only for generic programming (`T: Trait`, `impl Trait`, `dyn Trait`) or + as an extension trait (`FooExt`). Don't use traits merely to organize code. Put + essential functionality in inherent methods and have trait impls forward to them, so + callers need no import. +- Prefer, in order: concrete types; generics (`T: Trait`, `impl Trait`); `dyn Trait`, + ideally wrapped in your own struct (`struct DynStore(Arc)`). Generics give + static dispatch and inlining; trait objects give heterogeneous collections and smaller + binaries. Don't nest generics on service-level types (`Service` is fine; + `Service>` is not). +- Decide early whether a trait must be object-safe. Generic methods or `Self` outside the + receiver break it; exclude such methods with `where Self: Sized`. +- Keep required trait methods minimal and provide defaults for everything derivable from + them, as `Iterator` does from `next`. +- If a function has a clear receiver, make it a method. A computation with no receiver is + a free function, not `Database::check(params)`. Associated functions are for + construction. +- Closures: use the most general bound that works (`FnOnce` if called once, `FnMut` if it + mutates, else `Fn`) and prefer `Fn*` bounds to bare `fn` pointers. Closure parameters go + last; don't take more than one. +- Keep parameter order consistent across a crate: call-specific first, ubiquitous + context (loggers, allocators) last. +- Reach for a macro only when functions, generics, and traits cannot do the job. Prefer + `macro_rules!` to proc macros, make macro input look like the output it generates, and + never let a macro change a type's kind or a function's signature. + +### Refactoring someone else's code + +- Fix every smell the request is about, not just the cheap ones: clones that only + satisfy the borrow checker, `&String` / `&Vec` parameters, `unwrap` on fallible + paths, `Rc>` in signatures, `get_` getters, `bool` parameters, `+` string + concatenation, `#![deny(warnings)]`, error types without `Error`, nondeterministic + `HashMap` iteration in output. +- Keep public behavior identical unless changing it is the point: the same operations, + the same success and failure semantics, the same output bytes. Turning a panic into an + `Err` is the change callers want. Dropping an error variant, removing a derive, or + changing what a constructor takes is not; if a signature must change, show the before + and after in the change list and say why. +- "Keep the behaviour" protects what callers can rely on, not the smells you were asked + to remove. When the request is an idiom or API clean-up, fixing the smells listed above + is the point, even though each one changes a signature: rename `get_foo` to `foo`, turn + a `bool` parameter into an enum or two methods, and make a panic on caller input + (an unknown key, a bad line) return `Result` or `Option`. List each of these in the + change list with its before and after. `HashMap` iteration order was never defined, + so callers cannot rely on it: sort the output, or switch to `BTreeMap` or an ordered + `Vec`, and add a test that pins the order. +- Preserve quirks you don't understand and flag them, rather than silently "fixing" them. +- When the module has no tests, pin the current behavior with a few before you touch it. + +## 5. Errors and panics + +Pick the mechanism by contract: + +| Situation | Use | +|---|---| +| Absence is normal (`first()`, `checked_add`) | `Option` | +| The caller may need to know what went wrong | `Result` | +| A bug or violated invariant inside your code | `panic!` / `assert!` / `expect("why")` | + +**Panics are not exceptions.** A panic means "stop now". Never use one to report bad +input, never rely on `catch_unwind` for control flow (it does nothing under +`panic = "abort"` and can leave state inconsistent), and never catch a panic and continue +inside a library. Where a panicking convenience is justified, pair it with a fallible API +(`v[i]` / `v.get(i)`, `new` / `try_new`) and document it under `# Panics`. + +**Every intentional panic carries a message with the relevant values:** +`assert!(buf.len() >= HEADER, "buffer too small: {} bytes", buf.len())`, +`expect("config is loaded before workers start")`. Prefer `expect("reason")` to +`unwrap()`. Don't restate the condition as the message. + +**Pattern-match instead of check-then-unwrap:** `if let Some(v) = opt { .. }` or +`let Some(v) = opt else { return .. };`, never `if opt.is_some() { opt.unwrap() }`. + +**Lock poisoning is fatal:** `.lock().expect("lock poisoned")`. Don't recover with +`into_inner`. + +**Library error types** (any `E` in a public `Result`): + +- Implement `std::error::Error` (which requires `Debug` + `Display`), be + `Send + Sync + 'static`, and implement `source()` for wrapped causes. Never use `()`, + `String`, or `Box` as a library's public error type. +- `Display` messages are lowercase, concise, and have no trailing punctuation: + `"invalid header length"`. +- Implement `From` so `?` converts. Use `map_err` only for foreign errors or + to add context. +- Two sound shapes: an enum with one variant per cause (`thiserror` generates this + well), or a struct per situation with a private `kind` plus `is_xxx()` and accessor + methods. Either way, don't make one crate-wide enum that lists every failure mode in + the crate, and don't expose details callers cannot act on. +- If a fallible function consumes an argument, return it inside the error so the caller + can retry without cloning (`FromUtf8Error::into_bytes`). +- Never expose `anyhow::Error` in a library's public API. + +**Application error handling:** `anyhow` or `eyre` with `.context("opening config")` is +the right tool. Use one app-level error type, not several. `main` may return +`Result<(), anyhow::Error>`. + +**Destructors never fail, panic, or block.** Provide `close(self) -> Result<()>` for +fallible teardown and let `Drop` do best-effort cleanup. + +**Document failure modes:** `# Errors` for any `Result`, `# Panics` for any reachable +panic, `# Safety` for every `unsafe fn`. + +## 6. Everyday idioms + +- **Iterators over hand loops** when the pipeline is short and reads top-down: + `values.iter().filter(..).map(..).collect()`, `.any()`, `.sum()`, `.fold()`. Collect + fallible steps into `Result, E>` and apply `?`. Keep an explicit `for` loop when + the body is large, does several jobs, or needs awkward early returns. Bind a long chain + to a named variable rather than putting it in a `for` header, and prefer `for x in it` + to `.for_each(|x| ..)`. +- **`Option` / `Result` combinators** (`map`, `and_then`, `ok_or_else`, `unwrap_or_else`, + `as_ref`, `as_deref`) when they're clearer than `match`, and `match` when they're not. +- **`format!` / `write!`** with inline args (`format!("{name}: {count}")`) for + concatenation and substitution, not chained `+` or `str::replace`. `write!` into an + existing buffer in hot paths. +- **Explicit types where inference obscures intent:** on `.into()`, `.parse()`, + `.collect()`, and complex iterator results. Prefer `let x: Vec = ..` to a turbofish. +- **Drop guards for cleanup** that must run on early return or unwind. Bind them to a + name (`let _guard = ..`), because `let _ = ..` drops immediately. +- **Closures that capture mixed ownership:** rebind in a block, then `move`: + + ```rust + let job = { + let cfg = cfg.clone(); + move || run(cfg, data) + }; + ``` + +- **Import style:** one `use` per module path (`use foo::bar::{Bar, Baz};`); types and + traits imported and used unqualified (`Regex`); free functions qualified by their module + (`mem::take`, `fs::read`). Import a trait inside the function that needs it unless the + whole file uses it. No globs except `use super::*` in tests, `use Enum::*` in a function + that matches on it, and a framework's prelude such as `use bevy::prelude::*`. +- **Magic numbers** become named `const`s with a doc comment saying where the value + comes from and what changing it affects. +- **Logging:** structured events through `tracing` or `log`, not `println!` / `dbg!`, + except for a CLI's own stdout output. + +## 7. Concurrency and async + +- Public types, and the futures they return, should be `Send` (and usually `Sync`). Pin + it with a compile-time check so a refactor can't silently regress it: + + ```rust + const _: () = { + const fn assert_send() {} + assert_send::(); + }; + ``` + + Holding an `Rc` or a `RefCell` borrow across an `.await` makes a future `!Send`. +- Prefer message passing (channels) to shared state. When sharing is necessary: keep data + with linked invariants under one lock, keep lock scopes to a few lines, never call user + closures while holding a lock, and never return a `MutexGuard` from a public method. +- Write `async fn` rather than `fn -> impl Future`, except in traits or when setup must + run outside the async block for a hot path. +- Long CPU-bound work inside async must yield (`tokio::task::yield_now().await` every + tens of microseconds) or move to `spawn_blocking`. +- Library code doesn't spawn raw threads or assume a runtime; take an executor, a spawn + function, or `impl AsyncRead` / `impl Read` from the caller. + +## 8. Unsafe and FFI + +- Write `unsafe` only for one of three reasons: a novel abstraction safe code can't + express, a benchmarked performance need, or FFI and platform calls. Reach for std and + well-reviewed crates first; they already contain the audited `unsafe`. +- Every `unsafe` block or impl gets a `// SAFETY:` comment stating why the invariants + hold. Every `unsafe fn` gets a `# Safety` doc section listing what the caller must + uphold. Enable `unsafe_op_in_unsafe_fn`. +- Keep `unsafe` in the smallest module that can uphold its invariant and wrap it in a + safe API; the module boundary is the soundness boundary. A safe function that can cause + undefined behavior through any sequence of safe calls is unsound, and unsound code is + never acceptable. +- Mark a function `unsafe` only when misuse can cause undefined behavior, not because it + is dangerous (`delete_database()` is a safe function). +- No `transmute` to cast enums or dodge lifetimes, and no `unsafe impl Send` to silence + the compiler. +- Test unsafe code under Miri and with adversarial inputs. +- FFI: `#[repr(C)]` on shared structs, sized integer types, `CString` / `CStr` for + strings, allocate and free on the same side, wrap C-owned pointers in an RAII type whose + `Drop` frees them, check for null and return `Result`, and stop panics at the boundary + with `catch_unwind`. Generate bindings with `bindgen` in a `foo-sys` crate and keep + business logic in a safe core crate. + +## 9. Crates, modules, dependencies + +- **Prefer small, single-purpose crates** in a flat `crates/` workspace; never nest a + crate inside another crate's `src/`. Split when a crate grows a second purpose or a + subdirectory. Share versions and lints through `[workspace.dependencies]` and + `[workspace.lints]`. +- **Modules:** name a leaf module after its primary item (`Foo` lives in `foo.rs`). + Non-leaf modules contain only `mod` declarations and re-exports. Put the essential items + at the crate root and group the rest by use case (`account`, `network`), not by kind + (`traits`, `errors`). Don't define a prelude. +- **Re-export individually** (`pub use foo::{A, B};`), never with a glob. +- **Dependencies:** every one costs compile time, binary size, and supply-chain exposure, + including `build.rs` and proc macros. Use ranges (`"1"`, `"1.4"`), never `"*"` or a + needless `"="`. Commit `Cargo.lock` for binaries. Audit with `cargo tree --duplicates`, + `cargo deny`, `cargo udeps`, and `cargo audit`. +- **Features are additive and bare-named:** `std`, `serde`, `alloc`, `test-util`. Never + `no-std`, `use-serde`, or a feature that removes or changes a public item. Don't + feature-gate struct fields or trait methods. Put mocks and fakes behind `test-util`. +- **Semver:** breaking changes include removing or renaming public items, adding a + variant to an enum that isn't `#[non_exhaustive]`, adding a field to a publicly + constructible struct, adding a trait bound, or making a trait non-object-safe. + Deprecate in a minor release before removing in a major one. Use the latest stable + edition for new crates and set an MSRV deliberately. +- Don't run code before `main()` (no `ctor`-style crates). Don't use unstable features + on a stable toolchain. + +## 10. Documentation and comments + +- `///` on every public item; `//!` at the top of every public module and the crate root. + The first sentence is a single line of about fifteen words, because it becomes the + summary in listings. +- Sections, in this order, as applicable: `# Examples`, `# Errors`, `# Panics`, + `# Safety`. Examples use `?` with the `fn main` hidden behind `# ` lines, never + `unwrap()`, because users copy them verbatim. Describe parameters in prose, not a table. +- Document what the signature can't say: preconditions, side effects, ownership + transfer, complexity, and why. Don't restate the type or the name; + `/// Removes an element.` on `remove_element` is noise. +- Link items with `` [`Type`] ``. Hide impls users never trigger + (`From for PublicError`) with `#[doc(hidden)]`. +- `//` comments explain why, not what: `// SAFETY:`, `// TODO(issue-123):`, non-obvious + magic values, workarounds with a link. No design journals, "why we chose X" essays, or + rule-compliance tables in code docs. Document the end state. + +## 11. Tests + +- Unit tests in `#[cfg(test)] mod tests { use super::*; .. }` for private internals. + Integration tests in `tests/` for anything reachable through the public API, and prefer + that location when either would do. Doc examples are tests too. +- Test observable behavior and properties (monotonic, round-trips, idempotent), not + restated constants or mirrored branches. +- Write a failing test before fixing a bug. Cover each feature combination and each + platform-specific path. +- Anything doing I/O, time, randomness, or network must be mockable: + `new_mocked() -> (Self, MockCtrl)` behind `test-util`, not a `Default` that performs I/O. +- Fuzz parsers of untrusted input with `cargo fuzz`. Benchmark with `criterion` or `divan` + and `std::hint::black_box`. Run Miri over `unsafe`. +- Assertions get context so failures read well: `assert_eq!(got, want, "input {input:?}")`. + +## 12. Performance, in order + +Design for usability first and optimize after measuring. When you do: `Vec::with_capacity` +or `collect()` over push loops; reuse caller-owned buffers in hot APIs +(`fn read_into(&mut self, buf: &mut Vec)`); `Box<[T]>`, `Box`, `Arc` for +long-lived immutable sequences; `shrink_to_fit` on long-lived collections built without a +reservation; a faster hasher (`foldhash`, `FxHash`) only for trusted keys; batch work +instead of per-item locking; applications may set a `#[global_allocator]` such as +`mimalloc`. Derive `Copy` for small plain types and never for large ones. + +## 13. Final checklist + +Before returning Rust code, confirm: + +- `cargo fmt`, `cargo clippy -- -D warnings`, and `cargo test` are clean. +- No `unwrap()` outside tests and `main`; every `expect`, `assert`, and `panic` has a + message with the relevant values. +- Public functions take `&str`, `&[T]`, `impl AsRef<_>`, or `impl IntoIterator`, not + `&String` or `&Vec`. +- Every public type derives `Debug` and the applicable common traits; error types + implement `Error + Display + Send + Sync + 'static`. +- No `bool` parameters in public signatures; no hand-written `Ord` without matching + `PartialEq` and `Hash`. +- No `.clone()` whose only job is to satisfy the borrow checker. +- No globs (bar a framework's prelude), no preludes of your own, no leaked third-party types. +- Every `unsafe` block has a `// SAFETY:` comment; every `unsafe fn` has `# Safety` docs. +- Public items have docs with a one-line summary and `# Errors` / `# Panics` where relevant. +- Application code stayed simple; library code followed the API rules. + +## References + +Read these when you need the reasoning behind a rule or a complete checklist for a task. +Each is a condensed digest of one source. + +- [sources/rust-api-guidelines.md](./sources/rust-api-guidelines.md) (https://rust-lang.github.io/api-guidelines/): + designing a public API or crate; all 54 checklist items with conventions. +- [sources/effective-rust.md](./sources/effective-rust.md) (https://www.lurklurk.org/effective-rust/): choosing + between alternatives: generics vs `dyn`, `Result` vs panic, iterators vs loops, + borrow-checker tactics, dependencies, CI. +- [sources/rust-design-patterns.md](./sources/rust-design-patterns.md) (https://rust-unofficial.github.io/patterns/): + idioms, patterns, and anti-patterns with code. +- [sources/microsoft-rust-guidelines.md](./sources/microsoft-rust-guidelines.md) (https://microsoft.github.io/rust-guidelines/): + error struct design, panic policy, unsafe policy, async, workspace layout, performance. +- [sources/google-rust-style-guide.md](./sources/google-rust-style-guide.md) (https://google.github.io/styleguide/rustguide.html): + formatting, imports, module layout, accessor naming, application vs library. +- Bevy's digest is not included in this payload. For ECS work, consult the framework + version actually consumed and the optional BeautifulRust digest at the revision + recorded in [NOTICE.md](./NOTICE.md). Do not assume ordinary Rust patterns override + framework-specific scheduling and query contracts. diff --git a/skills/visioncraft/references/traceability.md b/skills/visioncraft/references/traceability.md new file mode 100644 index 0000000..1fd25c9 --- /dev/null +++ b/skills/visioncraft/references/traceability.md @@ -0,0 +1,73 @@ +# Trace requirements through delivery + +This reference retains the useful traceability concepts associated with BHIL +without requiring its scaffolding tools or copying a particular tool's schema. +Use the repository's existing identifiers and tracker. Paths or URLs are valid +references; there is no requirement for a second issue store. + +## Link the evidence-bearing chain + +Connect the product requirement to a specification, important decision, work +item, code revision, checks, review and release observation. Keep the reverse +links useful: a changed decision should reveal affected consumers and tests. +Do not invent a record at every step if the existing issue already carries it. + +For each link ask whether the referenced item exists, refers to the same scoped +behaviour and is current enough for this decision. Record supersession rather +than overwriting history. An ID proves addressability, not completion. The +[traceability worksheet](../assets/traceability.md) includes prompts, evaluations +and guardrails as ordinary linked artefacts. + +## Decisions specific to AI systems + +| Decision | Useful evidence and constraints | +|---|---| +| Model choice | Actual model identity, task-specific quality observations, cost/latency measurements, allowed data flow, re-evaluation trigger | +| Prompt strategy | Versioned prompt bytes, parsing/output contract, retrieval assumptions, paired evaluation and failure examples | +| Participant topology | Dependencies, concurrency limits, ownership, spend budget, cancellation and error propagation | +| Data/feature pipeline | Input/output meaning and dimensions, provenance, validation, resource budget, drift and fallback | + +These are decision categories, not built-in VisionCraft services. The actual +host supplies execution and measurements. + +## Choose a topology for the dependency graph + +A single coordinator with workers suits separable work whose results need one +owner. A pipeline suits ordered transformations. Parallel exploration helps +compare uncertain alternatives when its cost is justified. Peer collaboration +needs explicit ownership and conflict handling. Mixed arrangements can combine +these when the task has both independent and sequential phases. + +Do not infer latency, reliability or independence from the topology's name. +Record actual executions and distinguish a coordination record from a running +worker. Use only delegation already authorised by the task and environment. + +## Prompts and evaluations + +Version deployed prompt bytes alongside their output contract and evaluator. +Changing a required output shape can break consumers even if the prose looks +similar. Preserve immutable release versions, the linked decision, evaluation +revision, representative inputs and observed scores. Do not label a prompt +production-ready merely because an example produced plausible text. + +An evaluation should cover ordinary, boundary and adversarial inputs with +explicit assertions and a named judging method. Separate deterministic shape +checks from subjective quality rubrics. Define applicability for leakage, +untrusted-input handling, refusal and recovery behaviour; a refusal-only system +must not earn a green score by denying supported requests. Run suitable controls. + +Thresholds belong to the project and measured sample. Report denominators, +uncertainty and failure cases. If a required evaluator is unavailable, retain +that state rather than lowering the threshold after seeing results. + +## Guardrails and operating changes + +Specify accepted input, rejected input, output constraints, retained private +data, failure handling, fallback and escalation. State the authority needed for +external effects. Name observable monitoring signals and their response owner; +an alert percentage without an evaluator or action is only prose. + +For a sprint, reuse the current PRD/SPEC/ADR/task scaffolding if available. Turn +acceptance criteria into expectations and tests, then carry exact code/release +references back to the work item. Migration, consumer pinning and live runtime +observations need their own evidence even after the producer's release exists. diff --git a/skills/visioncraft/references/worked-examples.md b/skills/visioncraft/references/worked-examples.md new file mode 100644 index 0000000..2d07af7 --- /dev/null +++ b/skills/visioncraft/references/worked-examples.md @@ -0,0 +1,162 @@ +# Five projects, different evidence needs + +These are worked planning examples, not reports of executed projects. Choose +versions and limits from the actual project. Expected behaviours below define +example contracts; they do not claim test output, production readiness or a +universal percentage gate. + +## 1. A personal todo application + +**Request.** Add creation, editing, completion, deletion, filtering and local +persistence to a small browser app. Existing project conventions choose the UI +framework; no agent fleet or full domain programme is needed. + +**Expectation.** A saved item survives reload with its stable identity and +completion state. Editing its text preserves that identity. An empty title is +rejected without changing the previous item. Filtering changes the visible +set without deleting hidden items. Storage failure is reported without claiming +the edit was durably saved. + +**Implementation sequence.** Add a failing model test for state transitions, +implement the smallest reducer/store change, then test persistence through the +real browser storage boundary. Exercise create/edit/filter/reload in the browser. +Keep a valid ordinary title control beside empty and markup-like input cases. + +**Applicable gates.** Unit and browser journey checks; visible error behaviour; +keyboard operation, focus and appropriate labels; safe treatment of user text. +A small prototype may defer multi-device sync explicitly. Do not claim sync or +full accessibility conformance from these local checks. + +**Closeout.** Retain commands and browser observations with the source revision. +Link the reload and rejected-edit regression. Note unsupported storage contexts. +There is no reason to create a separate review ledger for this small change +unless the host workflow needs one. + +## 2. A task API with identity and project membership + +**Request.** Implement users, projects and tasks with authentication, role +checks, request limits and an API contract. Model Identity and Project +Management as separate concerns; membership policy owns access to project +resources. Use an ADR if choosing between materially different session/token +designs or changing the existing persistence model. + +**Expectation set for this example.** + +- A token has a stable subject ID and explicit issuance/expiry. For the example + contract, it expires at 3,600 seconds with no implicit grace or refresh. Test + just before/at/after the boundary with an injected clock and a wrong-key case. +- A rolling per-user/per-endpoint limit permits 100 requests in 60 seconds and + returns 429 plus a meaningful retry interval for the next. An anonymous policy + uses an explicitly chosen key. Preflight handling is an explicit case. +- An owner may delete a project; a member may read but not delete it. Choose + and document the existence-disclosure policy for outsiders and nonexistent + IDs. Neither 403 nor 404 is universally correct without that policy. +- The API description includes public routes and matches observed success and + error shapes. Schema validation alone does not establish route coverage. + +**Implementation sequence.** Characterise authentication and its consumers, +then red/green the admission boundary. Add project/task writes and consuming +reads with real test storage. Exercise owner, member, outsider and missing-ID +controls. Verify rejected mutations leave primary and secondary state unchanged. +Then validate API examples against actual responses. + +**Audit and stabilisation.** For the required security review, use an actual +independent auditor who sees the same source/configuration. A suggested new +probe is a fresh credential retry after an earlier rejected operation; whether +the auditor chooses that or another boundary is recorded. Keep expiry, limits +and membership checks as permanent regressions. Security threshold completion +and live deployment remain separate. + +## 3. Commerce with payments and inventory + +**Request.** Support catalogue browsing, persistent carts, checkout, order +history, inventory administration and notifications. Separate Shopping, +Fulfilment and Administration. Orders/payments are core; catalogue and messaging +are supporting contexts. Model cart/order identity and monetary units explicitly. + +**Expectations.** A discount precedes tax under the chosen rounding rule; an +empty cart has a defined result. Inventory reservation prevents overselling +under concurrent checkout. Duplicate payment callbacks do not duplicate the +order, stock deduction or notification. A timeout after a durable payment must +not turn a retry into another charge. Recovery reconciles the payment and order +states rather than inferring failure from an HTTP error. + +**Decisions.** Record provider boundary, authoritative order state, cart +persistence and optimistic versus pessimistic reservation when they involve +real tradeoffs. Preserve an existing settled protocol instead of adding a +parallel payment ledger or verifier. + +**Implementation sequence.** Establish catalogue and cart contracts; implement +money/order invariants with deterministic tests; then run payment-adapter +contract checks in an authorised test environment. Exercise callback replay, +fresh-token retries, process restart and dependency failure as separate cases. +Test notification effects after errors and migrations from old cart/order data. + +**Gates.** Critical regressions, provider/consumer compatibility, completed +security review, keyboard checkout, and bounded outage/recovery experiments. +A payment scanner does not certify regulatory compliance. State the actual +criteria and evidence required by the project. Any sandbox-only observation +remains sandbox evidence until production acceptance is observed. + +## 4. A project-scaffolding CLI + +**Request.** Provide `init`, `add`, `list` and `config` behaviours over named +templates. Keep a clear noninteractive path alongside optional prompts. These +names describe the example product, not VisionCraft commands. + +**Expectations.** Template files are created under the selected destination; +existing foreign files are not silently replaced. Unsupported input, missing +template and permissions failure have useful errors and stable exit semantics. +A rejected or interrupted run does not report a complete generated project. +Literal arguments remain literal and are not evaluated as shell syntax. + +**Implementation sequence.** Characterise listing/config output and error +contracts. Test one small supported template, then traversal, linked output +parents, conflicts, spaces and non-ASCII names. Inspect state after failure and +cancelled writes. If porting, carry over actual observable ordering and errors +while documenting deliberate differences and deleting only proven dead paths. + +**Gates.** CLI integration tests through the actual executable, a supported +generation control, output determinism where promised, parsing/path safety and +recovery tests. Use [Rust port guidance](rust/port.md) when applicable; a thin +wrapper over a language-specific dependency may be better left in place. + +**Closeout.** Retain a generated project fixture and validate it through its +own supported build, not merely by counting created files. Check installed +package behaviour separately from a local development binary. + +## 5. Real-time chat and presence + +**Request.** Add authenticated rooms, messages, typing/presence, paginated +history and image sharing. Identity, Messaging and Presence have different +authority, durability and loss requirements. A typed event is not proof of +delivery; presence can be ephemeral while messages require durable ordering. + +**Expectations.** A permitted member can send/read while an outsider cannot +access a known room/message ID. Reconnection recovers durable messages without +duplicating them. Revocation applies to the relevant existing connections. +Stale replaced sessions cannot inject poses or messages. A bounded lossy +presence queue must not swallow membership transitions needed for correct state. + +**Decisions.** Describe transport/subscription auth, durable history ownership, +pub/sub semantics, pagination and heartbeat expiry. Establish ordering and +clock assumptions explicitly. A topology label is not a scaling measurement. + +**Implementation sequence.** Test identity/room admission, then message storage +and readback. Drive multiple real clients through reconnect, logout, revocation, +replacement and pagination. Exercise uploads through validation and served +read paths; rejected content must not remain fetchable by a known identifier. + +**Gates.** Multi-client contract/end-to-end checks, security review, accessible +message navigation, workload measurements and bounded disconnection/resource +experiments. Choose connection counts and latency/loss budgets from the target, +measure them, and report the exact environment. Tests against one local +instance do not establish multi-replica admission or settlement guarantees. + +## Adapting the examples + +For data pipelines, add schema/units/provenance and restart/idempotency cases. +For mobile or hardware, distinguish simulation from actual device observation. +For AI features, link prompt/model versions to the relevant evaluation and +guardrails using [traceability](traceability.md). In every case, retain what was +actually observed and the explicit remaining acceptance conditions. From 348b086964938ba603a4cae94f7ea086245c2eac Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 3 Nov 2026 10:54:37 +0000 Subject: [PATCH 04/16] Implement bounded local execution and pinned Deepsec evidence adapter --- Cargo.toml | 2 +- src/deepsec.rs | 995 ++++++++++++++++++++++++++++++++++++++ src/deepsec_evidence.rs | 308 ++++++++++++ src/lib.rs | 8 + src/process.rs | 397 +++++++++++++++ tests/deepsec.rs | 207 ++++++++ tests/fixtures/deepsec.py | 52 ++ tests/process.rs | 171 +++++++ 8 files changed, 2139 insertions(+), 1 deletion(-) create mode 100644 src/deepsec.rs create mode 100644 src/deepsec_evidence.rs create mode 100644 src/process.rs create mode 100644 tests/deepsec.rs create mode 100644 tests/fixtures/deepsec.py create mode 100644 tests/process.rs diff --git a/Cargo.toml b/Cargo.toml index bcf5c3f..42294c7 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -31,7 +31,7 @@ tempfile = { version = "3.27", optional = true } url = { version = "2.5", optional = true } [target.'cfg(unix)'.dependencies] -nix = { version = "0.31.3", features = ["process", "signal"], optional = true } +nix = { version = "0.31.3", features = ["process", "signal", "fs"], optional = true } signal-hook = { version = "0.3", optional = true } [lints.rust] diff --git a/src/deepsec.rs b/src/deepsec.rs new file mode 100644 index 0000000..0784181 --- /dev/null +++ b/src/deepsec.rs @@ -0,0 +1,995 @@ +//! Executed Deepsec 2.3.10 gates with explicit policy and retained error states. +//! +//! This adapter knows no Agentbox manifest, memory service or network address. +//! Hosts project their policy into [`DeepsecPolicy`]. Credentials remain named +//! environment variables and are passed only to the model-processing child. + +use crate::process::{Termination, private_directory, private_file, run_command}; +use crate::{Invocation, from_json, sha256}; +use clap::{ArgGroup, Args}; +use serde::{Deserialize, Serialize}; +use serde_json::{Value, json}; +use std::collections::BTreeMap; +use std::fs::{self, File, OpenOptions}; +use std::io::{Read, Write}; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicBool, AtomicU64, Ordering}; +use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH}; + +#[path = "deepsec_evidence.rs"] +mod recorded; + +const VERSION: &str = "2.3.10"; +const SEVERITIES: [&str; 6] = ["CRITICAL", "HIGH", "MEDIUM", "HIGH_BUG", "BUG", "LOW"]; +static ATTEMPT: AtomicU64 = AtomicU64::new(0); + +/// Host-projected policy. Values are configuration; credential values are absent. +#[derive(Debug, Clone, Serialize, Deserialize)] +#[serde(default, deny_unknown_fields)] +pub struct DeepsecPolicy { + /// Whether paid/model processing is allowed at all. + pub enabled: bool, + /// Deepsec agent plugin: claude, codex or pi. + pub agent: String, + /// Authentication route: local, direct or custom. + pub model_auth: String, + /// Optional model override; empty leaves selection to the pinned tool. + pub model: String, + /// Deepsec thinking-level parameter. + pub thinking_level: String, + /// Inclusive severity threshold; lower findings remain visible. + pub fail_on: String, + /// Whole attempt deadline, including probes/export (for example `45m`). + pub max_duration: String, + /// Files per model batch. + pub batch_size: u32, + /// Maximum concurrent batches inside Deepsec. + pub concurrency: u32, + /// Provider identifier for direct/custom authentication. + pub ai_provider: String, + /// Name of a credential environment variable, never its value. + pub ai_api_key_env: String, + /// Optional custom/direct base URL, without credentials or query strings. + pub ai_base_url: String, + /// Non-secret policy origin for receipts. + pub policy_source: String, + /// Combined stdout/stderr bound for each child, at most one GiB. + pub max_output_bytes: u64, +} + +impl Default for DeepsecPolicy { + fn default() -> Self { + Self { + enabled: true, + agent: "claude".into(), + model_auth: "local".into(), + model: String::new(), + thinking_level: "high".into(), + fail_on: "HIGH".into(), + max_duration: "45m".into(), + batch_size: 5, + concurrency: 2, + ai_provider: String::new(), + ai_api_key_env: String::new(), + ai_base_url: String::new(), + policy_source: "defaults".into(), + max_output_bytes: 16 * 1024 * 1024, + } + } +} + +/// Adapter input/runtime error with the documented legacy-compatible exit code. +#[derive(Debug, thiserror::Error)] +#[error("{message}")] +pub struct GateError { + /// 70 runtime, 78 configuration/unavailable, 124 timeout, or 130 interruption. + pub code: i32, + /// Message deliberately excludes raw configuration and credential values. + pub message: String, +} + +fn error(code: i32, message: impl Into) -> GateError { + GateError { + code, + message: message.into(), + } +} +fn io_error(_: std::io::Error) -> GateError { + error(70, "evidence filesystem operation failed") +} + +fn duration_ms(text: &str) -> Option { + let (number, scale) = if let Some(n) = text.strip_suffix("ms") { + (n, 1_u64) + } else if let Some(n) = text.strip_suffix('s') { + (n, 1000) + } else if let Some(n) = text.strip_suffix('m') { + (n, 60_000) + } else if let Some(n) = text.strip_suffix('h') { + (n, 3_600_000) + } else if let Some(n) = text.strip_suffix('d') { + (n, 86_400_000) + } else { + (text, 1000) + }; + let (whole, fraction) = number.split_once('.').unwrap_or((number, "")); + if whole.is_empty() + || !whole.bytes().all(|c| c.is_ascii_digit()) + || fraction.len() > 3 + || !fraction.bytes().all(|c| c.is_ascii_digit()) + { + return None; + } + let base = whole.parse::().ok()?.checked_mul(scale)?; + let part = if fraction.is_empty() { + 0 + } else { + fraction.parse::().ok()?.checked_mul(scale)? / 10_u64.pow(fraction.len() as u32) + }; + base.checked_add(part) + .filter(|ms| (1..=86_400_000).contains(ms)) +} + +impl DeepsecPolicy { + /// Validate policy and return the whole-attempt deadline in milliseconds. + /// No environment is read and no process is started. + pub fn validate(&self) -> Result { + if !["claude", "codex", "pi"].contains(&self.agent.as_str()) { + return Err(error(78, "unsupported Deepsec agent")); + } + if !["local", "direct", "custom"].contains(&self.model_auth.as_str()) { + return Err(error(78, "unsupported model authentication route")); + } + if !["minimal", "low", "medium", "high", "xhigh"].contains(&self.thinking_level.as_str()) { + return Err(error(78, "unsupported thinking level")); + } + if !SEVERITIES.contains(&self.fail_on.as_str()) { + return Err(error(78, "unsupported severity threshold")); + } + if !(1..=100).contains(&self.batch_size) + || !(1..=32).contains(&self.concurrency) + || !(1..=1_073_741_824).contains(&self.max_output_bytes) + { + return Err(error(78, "invalid batch, concurrency or output bound")); + } + if [&self.model, &self.policy_source, &self.ai_provider] + .iter() + .any(|x| x.contains('\0')) + { + return Err(error(78, "invalid policy string")); + } + if !self.ai_api_key_env.is_empty() + && !(self + .ai_api_key_env + .as_bytes() + .first() + .is_some_and(|c| c.is_ascii_alphabetic() || *c == b'_') + && self + .ai_api_key_env + .bytes() + .all(|c| c.is_ascii_alphanumeric() || c == b'_')) + { + return Err(error(78, "invalid credential environment name")); + } + if !self.ai_base_url.is_empty() { + let url = url::Url::parse(&self.ai_base_url) + .map_err(|_| error(78, "invalid model base URL"))?; + if !["http", "https"].contains(&url.scheme()) + || url.host_str().is_none() + || !url.username().is_empty() + || url.password().is_some() + || url.query().is_some() + || url.fragment().is_some() + { + return Err(error( + 78, + "base URL must be HTTP(S), without credentials, query or fragment", + )); + } + } + match self.model_auth.as_str() { + "local" if self.agent == "pi" => { + return Err(error(78, "local authentication requires claude or codex")); + } + "direct" + if !["anthropic", "openai"].contains(&self.ai_provider.as_str()) + || self.ai_api_key_env.is_empty() => + { + return Err(error( + 78, + "direct authentication requires a supported provider and credential name", + )); + } + "custom" + if self.agent != "pi" + || self.ai_api_key_env.is_empty() + || self.ai_base_url.is_empty() => + { + return Err(error( + 78, + "custom authentication requires pi, a credential name and a base URL", + )); + } + _ => (), + } + duration_ms(&self.max_duration).ok_or_else(|| { + error( + 78, + "invalid duration; use positive seconds/ms/m/h/d up to one day", + ) + }) + } +} + +/// Deepsec gate flags. Mutually exclusive source modes are checked by Clap. +#[derive(Debug, Clone, Args)] +#[command(group(ArgGroup::new("source").required(true).multiple(false).args(["diff", "diff_working", "diff_staged", "files_from", "full", "scan_only"])))] +pub struct DeepsecOptions { + /// Compare against this Git reference. + #[arg(long)] + pub diff: Option, + /// Review working and untracked changes. + #[arg(long)] + pub diff_working: bool, + /// Review staged changes. + #[arg(long)] + pub diff_staged: bool, + /// Read newline-delimited file paths, or `-` for stdin. + #[arg(long)] + pub files_from: Option, + /// Scan and process the entire repository. + #[arg(long)] + pub full: bool, + /// Scan without model processing; result is SCANNED, not review PASS. + #[arg(long)] + pub scan_only: bool, + /// Source root, otherwise the nearest containing Git worktree or cwd. + #[arg(long)] + pub root: Option, + /// Fresh output directory; existing directories are refused. + #[arg(long)] + pub report_dir: Option, + /// Typed JSON policy from a host adapter; contains credential names only. + #[arg(long)] + pub policy_json: Option, + /// Override the severity threshold. + #[arg(long)] + pub fail_on: Option, + /// Override the thinking level. + #[arg(long)] + pub thinking_level: Option, + /// Override the Deepsec agent. + #[arg(long)] + pub agent: Option, + /// Override the model identifier. + #[arg(long)] + pub model: Option, + /// Override the authentication route. + #[arg(long)] + pub model_auth: Option, + /// Print the resolved plan without running any command or writing evidence. + #[arg(long)] + pub dry_run: bool, +} + +fn root_for(options: &DeepsecOptions) -> Result { + let path = if let Some(root) = &options.root { + root.clone() + } else { + let cwd = std::env::current_dir().map_err(io_error)?; + cwd.ancestors() + .find(|p| p.join(".git").exists()) + .unwrap_or(&cwd) + .to_owned() + }; + let path = path + .canonicalize() + .map_err(|_| error(78, "source root is unavailable"))?; + if !path.is_dir() { + return Err(error(78, "source root must be a directory")); + } + Ok(path) +} + +fn environment(policy: &DeepsecPolicy, model: bool) -> Vec { + let mut names: Vec = [ + "PATH", + "HOME", + "LANG", + "LC_ALL", + "TMPDIR", + "SSL_CERT_FILE", + "SSL_CERT_DIR", + "NODE_EXTRA_CA_CERTS", + "HTTP_PROXY", + "HTTPS_PROXY", + "ALL_PROXY", + "NO_PROXY", + "http_proxy", + "https_proxy", + "all_proxy", + "no_proxy", + ] + .into_iter() + .map(str::to_owned) + .collect(); + if model { + names.extend( + ["CLAUDE_CODE_EXECUTABLE", "CLAUDE_CONFIG_DIR", "CODEX_HOME"] + .into_iter() + .map(str::to_owned), + ); + if policy.model_auth == "local" { + names.push("CLAUDE_CODE_OAUTH_TOKEN".into()); + } else { + names.push(policy.ai_api_key_env.clone()); + } + } + names.sort(); + names.dedup(); + names +} + +fn write_new(path: &Path, bytes: &[u8]) -> Result<(), GateError> { + let parent = path + .parent() + .ok_or_else(|| error(70, "evidence path has no parent"))?; + let mut temporary = tempfile::NamedTempFile::new_in(parent).map_err(io_error)?; + temporary.write_all(bytes).map_err(io_error)?; + temporary.as_file().sync_all().map_err(io_error)?; + temporary + .persist_noclobber(path) + .map_err(|_| error(70, "evidence output already exists or cannot be finalised"))?; + Ok(()) +} + +fn read_bounded(path: &Path, limit: u64) -> Result, GateError> { + let meta = fs::symlink_metadata(path).map_err(io_error)?; + if !meta.is_file() || meta.file_type().is_symlink() || meta.len() > limit { + return Err(error(70, "evidence must be a bounded regular file")); + } + let mut bytes = Vec::new(); + File::open(path) + .map_err(io_error)? + .take(limit + 1) + .read_to_end(&mut bytes) + .map_err(io_error)?; + if bytes.len() as u64 > limit { + return Err(error(70, "evidence exceeded its byte bound")); + } + Ok(bytes) +} + +fn findings(bytes: &[u8]) -> Result, GateError> { + let value: StrictJson = serde_json::from_slice(bytes) + .map_err(|_| error(70, "malformed or ambiguous findings JSON"))?; + let value = value.0; + let rows = value + .as_array() + .or_else(|| value.get("findings").and_then(Value::as_array)) + .ok_or_else(|| error(70, "unrecognised findings export shape"))?; + let mut output = Vec::new(); + for row in rows { + if row.get("severity").is_some() { + output.push(row.clone()); + } else if let Some(nested) = row.get("findings").and_then(Value::as_array) { + for finding in nested { + let mut object = finding + .as_object() + .cloned() + .ok_or_else(|| error(70, "finding must be an object"))?; + if let Some(path) = row.get("filePath") { + object.entry("filePath").or_insert_with(|| path.clone()); + } + output.push(Value::Object(object)); + } + } else { + return Err(error(70, "unrecognised finding row")); + } + } + for finding in &mut output { + let severity = finding + .get("severity") + .and_then(Value::as_str) + .ok_or_else(|| error(70, "finding lacks a string severity"))? + .to_ascii_uppercase(); + if !SEVERITIES.contains(&severity.as_str()) { + return Err(error(70, "finding has an unrecognised severity")); + } + finding["severity"] = Value::String(severity); + } + Ok(output) +} + +// Findings come from an external protocol. Reject duplicate keys at every level, +// including severity and findings, rather than silently accepting the last key. +struct StrictJson(Value); +impl<'de> Deserialize<'de> for StrictJson { + fn deserialize>(deserializer: D) -> Result { + struct Visitor; + impl<'de> serde::de::Visitor<'de> for Visitor { + type Value = StrictJson; + fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str("unambiguous JSON") + } + fn visit_bool(self, v: bool) -> Result { + Ok(StrictJson(Value::Bool(v))) + } + fn visit_i64(self, v: i64) -> Result { + Ok(StrictJson(Value::Number(v.into()))) + } + fn visit_u64(self, v: u64) -> Result { + Ok(StrictJson(Value::Number(v.into()))) + } + fn visit_f64(self, v: f64) -> Result { + serde_json::Number::from_f64(v) + .map(|n| StrictJson(Value::Number(n))) + .ok_or_else(|| E::custom("non-finite JSON")) + } + fn visit_str(self, v: &str) -> Result { + Ok(StrictJson(Value::String(v.into()))) + } + fn visit_string(self, v: String) -> Result { + Ok(StrictJson(Value::String(v))) + } + fn visit_unit(self) -> Result { + Ok(StrictJson(Value::Null)) + } + fn visit_seq>( + self, + mut seq: A, + ) -> Result { + let mut values = Vec::new(); + while let Some(value) = seq.next_element::()? { + values.push(value.0); + } + Ok(StrictJson(Value::Array(values))) + } + fn visit_map>( + self, + mut map: A, + ) -> Result { + let mut values = serde_json::Map::new(); + while let Some(key) = map.next_key::()? { + if values.contains_key(&key) { + return Err(serde::de::Error::custom("duplicate JSON key")); + } + values.insert(key, map.next_value::()?.0); + } + Ok(StrictJson(Value::Object(values))) + } + } + deserializer.deserialize_any(Visitor) + } +} + +struct Attempt<'a> { + policy: &'a DeepsecPolicy, + report: &'a Path, + cancelled: &'a AtomicBool, + started: Instant, + deadline: Duration, + sequence: u32, +} + +impl Attempt<'_> { + fn command( + &mut self, + stage: &str, + program: &str, + args: Vec, + cwd: &Path, + model: bool, + stdin: bool, + ) -> Result<(i32, Vec), GateError> { + let remaining = self + .deadline + .checked_sub(self.started.elapsed()) + .filter(|v| !v.is_zero()) + .ok_or_else(|| error(124, "whole-attempt deadline reached"))?; + let directory = self.report.join(format!("{:02}-{stage}", self.sequence)); + self.sequence += 1; + private_directory(&directory).map_err(io_error)?; + let invocation = Invocation { + program: program.into(), + args, + cwd: ".".into(), + env: environment(self.policy, model), + timeout_ms: remaining.as_millis().max(1).try_into().unwrap_or(u64::MAX), + max_output_bytes: self.policy.max_output_bytes, + }; + write_new( + &directory.join("invocation.json"), + &serde_json::to_vec_pretty(&invocation) + .map_err(|_| error(70, "invocation serialisation failed"))?, + )?; + let run = + run_command(&invocation, cwd, &directory, self.cancelled, stdin).map_err(io_error)?; + let stdout = read_bounded(&run.stdout, self.policy.max_output_bytes)?; + let stderr = read_bounded(&run.stderr, self.policy.max_output_bytes)?; + let mut log = OpenOptions::new() + .append(true) + .open(self.report.join("deepsec.log")) + .map_err(io_error)?; + log.write_all(&stdout) + .and_then(|_| log.write_all(&stderr)) + .map_err(io_error)?; + let execution = json!({"stage":stage,"process":format!("{:?}",run.termination),"exit_code":run.exit_code,"signal":run.signal,"started_at_ms":run.started_at_ms,"finished_at_ms":run.finished_at_ms,"elapsed_ms":run.elapsed_ms,"stdout_sha256":sha256(&stdout),"stderr_sha256":sha256(&stderr),"error":run.error}); + write_new( + &directory.join("execution.json"), + &serde_json::to_vec_pretty(&execution) + .map_err(|_| error(70, "execution serialisation failed"))?, + )?; + match run.termination { + Termination::Completed if run.signal.is_none() => Ok(( + run.exit_code + .ok_or_else(|| error(70, "missing exit status"))?, + stdout, + )), + Termination::Unavailable => Err(error(78, "required executable is unavailable")), + Termination::TimedOut => Err(error( + 124, + "whole-attempt deadline reached; checkpoint evidence retained", + )), + Termination::Interrupted => Err(error( + 130, + "review interrupted; checkpoint evidence retained", + )), + _ => Err(error(70, "review process or capture did not complete")), + } + } +} + +#[cfg(unix)] +fn workspace_lock(workspace: &Path) -> Result, GateError> { + use nix::fcntl::{Flock, FlockArg}; + use std::os::unix::fs::OpenOptionsExt; + let path = workspace.join(".visioncraft.lock"); + if fs::symlink_metadata(&path).is_ok_and(|m| !m.is_file() || m.file_type().is_symlink()) { + return Err(error(78, "invalid review workspace lock")); + } + let file = OpenOptions::new() + .create(true) + .truncate(false) + .read(true) + .write(true) + .mode(0o600) + .open(path) + .map_err(io_error)?; + Flock::lock(file, FlockArg::LockExclusiveNonblock) + .map_err(|_| error(78, "another review owns this workspace")) +} + +/// Execute an explicitly requested security gate, returning its legacy exit code. +/// +/// Dry-run prints only the resolved plan. Completed, failed and interrupted +/// attempts write fresh receipts; unknown exports and incomplete execution can +/// never be interpreted as an empty successful review. +pub fn execute(options: &DeepsecOptions, cancelled: &AtomicBool) -> Result { + let modes = [ + options.diff.is_some(), + options.diff_working, + options.diff_staged, + options.files_from.is_some(), + options.full, + options.scan_only, + ]; + if modes.into_iter().filter(|x| *x).count() != 1 + || options.diff.as_ref().is_some_and(|v| v.trim().is_empty()) + { + return Err(error(78, "choose exactly one nonempty source mode")); + } + #[cfg(not(unix))] + { + let _ = (options, cancelled); + Err(error(78, "Deepsec process adapter requires Unix")) + } + #[cfg(unix)] + { + let mut policy = match &options.policy_json { + Some(text) => from_json::(text.as_bytes()) + .map_err(|_| error(78, "invalid policy JSON"))?, + None => DeepsecPolicy::default(), + }; + if let Some(v) = &options.agent { + policy.agent = v.clone(); + } + if let Some(v) = &options.model { + policy.model = v.clone(); + } + if let Some(v) = &options.model_auth { + policy.model_auth = v.clone(); + } + if let Some(v) = &options.thinking_level { + policy.thinking_level = v.clone(); + } + if let Some(v) = &options.fail_on { + policy.fail_on = v.to_ascii_uppercase(); + } + let deadline_ms = policy.validate()?; + if !policy.enabled { + return Err(error( + 78, + "Deepsec gate disabled by policy; record SKIPPED, not passed", + )); + } + let root = root_for(options)?; + let cwd = std::env::current_dir().map_err(io_error)?; + let files = match &options.files_from { + Some(path) if path == Path::new("-") => Some(path.clone()), + Some(path) => { + let path = cwd + .join(path) + .canonicalize() + .map_err(|_| error(78, "file manifest is unavailable"))?; + read_bounded(&path, 8 * 1024 * 1024) + .map_err(|_| error(78, "file manifest must be a readable bounded file"))?; + Some(path) + } + None => None, + }; + let mode = if options.scan_only { + "scan-only" + } else if options.full { + "full" + } else if files.is_some() { + "files-from" + } else if options.diff_working { + "diff-working" + } else if options.diff_staged { + "diff-staged" + } else { + "diff" + }; + let workspace = root.join(".deepsec-gate"); + let now = SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .as_millis(); + let attempt_id = format!( + "{now}-{}-{}", + std::process::id(), + ATTEMPT.fetch_add(1, Ordering::SeqCst) + ); + let report = options + .report_dir + .as_ref() + .map(|p| cwd.join(p)) + .unwrap_or_else(|| workspace.join("reports").join(&attempt_id)); + let project_id: String = root + .file_name() + .map_or_else(|| "project".into(), |v| v.to_string_lossy()) + .chars() + .map(|c| { + if c.is_ascii_alphanumeric() || "_.-".contains(c) { + c + } else { + '-' + } + }) + .collect(); + let mut route = match policy.model_auth.as_str() { + "local" => json!({"mode":"local","provider":"local"}), + "direct" => { + json!({"mode":"direct","provider":policy.ai_provider,"apiKeyEnv":policy.ai_api_key_env}) + } + _ => { + json!({"mode":"custom","provider":if policy.ai_provider.is_empty(){"custom"}else{&policy.ai_provider},"apiKeyEnv":policy.ai_api_key_env,"credentialHeader":{"name":"authorization","scheme":"bearer"}}) + } + }; + if !policy.ai_base_url.is_empty() { + route["baseUrl"] = json!(policy.ai_base_url); + } + let plan = json!({"version":1,"attempt_id":attempt_id,"mode":mode,"diff_ref":options.diff,"files_from":files,"root":root,"project_id":project_id,"workspace":workspace,"report_dir":report,"deepsec_version_required":VERSION,"policy":policy,"route":route}); + if options.dry_run { + println!( + "{}", + serde_json::to_string_pretty(&plan) + .map_err(|_| error(70, "plan serialisation failed"))? + ); + return Ok(0); + } + if !options.scan_only + && policy.model_auth != "local" + && std::env::var_os(&policy.ai_api_key_env).is_none_or(|v| v.is_empty()) + { + return Err(error( + 78, + "configured credential environment variable is unset", + )); + } + match fs::symlink_metadata(&workspace) { + Ok(meta) if meta.is_dir() && !meta.file_type().is_symlink() => (), + Ok(_) => return Err(error(78, "review workspace must be an ordinary directory")), + Err(e) if e.kind() == std::io::ErrorKind::NotFound => { + private_directory(&workspace).map_err(io_error)? + } + Err(_) => return Err(error(70, "review workspace unavailable")), + } + use std::os::unix::fs::PermissionsExt; + fs::set_permissions(&workspace, fs::Permissions::from_mode(0o700)).map_err(io_error)?; + let _lock = workspace_lock(&workspace)?; + if fs::symlink_metadata(&report).is_ok() { + return Err(error(78, "report directory must be new")); + } + private_directory(&report).map_err(io_error)?; + let _log = private_file(&report.join("deepsec.log")).map_err(io_error)?; + write_new( + &report.join("plan.json"), + &serde_json::to_vec_pretty(&plan) + .map_err(|_| error(70, "plan serialisation failed"))?, + )?; + if !workspace.join(".gitignore").exists() { + write_new(&workspace.join(".gitignore"), b"*\n")?; + } + let config = workspace.join("deepsec.config.mjs"); + if fs::symlink_metadata(&config).is_ok_and(|m| !m.is_file() || m.file_type().is_symlink()) { + return Err(error(78, "configuration path is not an ordinary file")); + } + let config_value = + json!({"ai":route,"projects":[{"id":project_id,"root":root}],"dataDir":"./data"}); + let config_text = format!( + "// Generated by VisionCraft; credential names only.\nexport default {};\n", + serde_json::to_string_pretty(&config_value) + .map_err(|_| error(70, "configuration serialisation failed"))? + ); + let mut staged = tempfile::NamedTempFile::new_in(&workspace).map_err(io_error)?; + staged.write_all(config_text.as_bytes()).map_err(io_error)?; + staged.as_file().sync_all().map_err(io_error)?; + staged + .persist(&config) + .map_err(|_| error(70, "cannot finalise review configuration"))?; + let mut attempt = Attempt { + policy: &policy, + report: &report, + cancelled, + started: Instant::now(), + deadline: Duration::from_millis(deadline_ms), + sequence: 0, + }; + let mut revision = "unknown".to_owned(); + let mut dirty: Option = None; + let outcome = (|| -> Result { + let (rc, version) = attempt.command( + "version", + "deepsec", + vec!["--version".into()], + &workspace, + false, + false, + )?; + if rc != 0 + || String::from_utf8_lossy(&version) + .trim() + .trim_start_matches("deepsec ") + != VERSION + { + return Err(error( + 78, + "Deepsec version does not match the verified 2.3.10 protocol", + )); + } + let (rc, bytes) = attempt.command( + "revision", + "git", + vec!["rev-parse".into(), "HEAD".into()], + &root, + false, + false, + )?; + if rc == 0 { + revision = String::from_utf8_lossy(&bytes).trim().to_owned(); + } + let (rc, bytes) = attempt.command( + "dirty", + "git", + vec!["status".into(), "--porcelain".into()], + &root, + false, + false, + )?; + if rc == 0 { + dirty = Some(!bytes.is_empty()); + } + let selected = recorded::select(options, files.as_deref(), &mut attempt, &root)?; + let before = recorded::snapshot(&root, &selected)?; + write_new( + &report.join("inputs-before.json"), + &serde_json::to_vec_pretty(&before) + .map_err(|_| error(70, "source encoding failed"))?, + )?; + let source_list = report.join("selected-files.txt"); + write_new( + &source_list, + format!("{}\n", selected.join("\n")).as_bytes(), + )?; + let data = workspace.join("data").join(&project_id); + let common = vec![ + "--project-id".into(), + project_id.clone(), + "--root".into(), + root.to_string_lossy().into_owned(), + ]; + let mut model_args = vec![ + "--agent".into(), + policy.agent.clone(), + "--thinking-level".into(), + policy.thinking_level.clone(), + "--batch-size".into(), + policy.batch_size.to_string(), + "--concurrency".into(), + policy.concurrency.to_string(), + ]; + if !policy.model.is_empty() { + model_args.extend(["--model".into(), policy.model.clone()]); + } + if options.scan_only || options.full { + let mut args = vec!["scan".into()]; + args.extend(common.clone()); + let (rc, _) = attempt.command("scan", "deepsec", args, &workspace, false, false)?; + if rc != 0 { + return Err(error(70, "Deepsec scan failed")); + } + if options.scan_only { + return Ok( + json!({"result":"SCANNED","deepsec_exit":0,"findings_by_severity":{},"blocking":[],"boundary":"Scan-only is not a completed model review."}), + ); + } + } + let expected = if options.full { + recorded::pending(&data, &before)? + } else { + before.clone() + }; + let prior_runs = recorded::run_files(&data)?; + let mut args = vec!["process".into()]; + if !options.full { + args.extend([ + "--files-from".into(), + source_list.to_string_lossy().into_owned(), + "--no-ignore".into(), + ]); + } + args.extend(common); + args.extend(model_args); + if !options.full { + args.extend([ + "--comment-out".into(), + report.join("comment.md").to_string_lossy().into_owned(), + ]); + } + let (rc, _) = attempt.command("process", "deepsec", args, &workspace, true, false)?; + if (options.full && rc != 0) || (!options.full && ![0, 1].contains(&rc)) { + return Err(error(70, "Deepsec processing failed")); + } + if rc == 1 + && read_bounded(&report.join("comment.md"), policy.max_output_bytes) + .map_or(true, |b| b.is_empty()) + { + return Err(error( + 70, + "exit 1 without fresh completed findings evidence", + )); + } + let after = recorded::snapshot(&root, &selected)?; + write_new( + &report.join("inputs-after.json"), + &serde_json::to_vec_pretty(&after) + .map_err(|_| error(70, "source encoding failed"))?, + )?; + if before != after { + return Err(error(70, "review inputs changed while the reviewer ran")); + } + let observed = recorded::validate_review( + &data, + &prior_runs, + &expected, + &root, + &project_id, + &report, + )?; + let args = vec![ + "export".into(), + "--project-id".into(), + project_id.clone(), + "--format".into(), + "json".into(), + "--min-severity".into(), + "LOW".into(), + "--out".into(), + report.join("findings.json").to_string_lossy().into_owned(), + ]; + let (export_rc, _) = + attempt.command("export", "deepsec", args, &workspace, false, false)?; + if export_rc != 0 { + return Err(error(70, "Deepsec findings export failed")); + } + let raw = read_bounded(&report.join("findings.json"), policy.max_output_bytes)?; + let findings = findings(&raw)?; + if rc == 1 && findings.is_empty() { + return Err(error(70, "findings exit with an empty export")); + } + let mut counts: BTreeMap<&str, usize> = + SEVERITIES.into_iter().map(|s| (s, 0)).collect(); + let threshold = SEVERITIES + .iter() + .position(|s| *s == policy.fail_on) + .expect("validated threshold"); + let mut blocking = Vec::new(); + for finding in &findings { + let severity = finding["severity"].as_str().expect("validated severity"); + *counts.get_mut(severity).expect("known severity") += 1; + if SEVERITIES + .iter() + .position(|s| *s == severity) + .expect("known severity") + <= threshold + { + blocking.push(finding.clone()); + } + } + Ok( + json!({"result":if blocking.is_empty(){"PASS"}else{"BLOCK"},"deepsec_exit":rc,"findings_by_severity":counts,"blocking":blocking,"findings_total":findings.len(),"observed_review":observed,"raw_export_sha256":sha256(&raw),"net_new_reported_by_deepsec":if options.full{None}else{Some(rc==1)},"boundary":"Threshold result over the raw export; historical findings may be included. Observed coverage is listed separately; semantic truth is not inferred."}), + ) + })(); + let (mut receipt, exit) = match outcome { + Ok(value) => { + let code = if value["result"] == "BLOCK" { 1 } else { 0 }; + (value, code) + } + Err(err) => ( + json!({"result":match err.code {124=>"TIMEOUT",130=>"INTERRUPTED",78=>"UNAVAILABLE",_=>"ERROR"},"error":err.message}), + err.code, + ), + }; + let object = receipt.as_object_mut().expect("receipt object"); + object.extend(json!({"schema_version":1,"gate":"deepsec","attempt_id":attempt_id,"mode":mode,"revision":revision,"dirty":dirty,"deepsec_version":VERSION,"policy_source":policy.policy_source,"fail_on":policy.fail_on,"report_dir":report,"state_dir":workspace,"elapsed_ms":attempt.started.elapsed().as_millis(),"plan_sha256":sha256(&serde_json::to_vec(&plan).map_err(|_|error(70,"plan encoding failed"))?)}).as_object().expect("object").clone()); + write_new( + &report.join("receipt.json"), + &serde_json::to_vec_pretty(&receipt) + .map_err(|_| error(70, "receipt encoding failed"))?, + )?; + println!( + "{}", + serde_json::to_string_pretty(&receipt) + .map_err(|_| error(70, "receipt encoding failed"))? + ); + Ok(exit) + } +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn duration_and_policy_refuse_unbounded_or_secret_urls() { + assert_eq!(duration_ms("0.25s"), Some(250)); + assert_eq!(duration_ms("45m"), Some(2_700_000)); + for bad in ["NaNs", "-1s", "0s", "100d", "1.2.3s"] { + assert_eq!(duration_ms(bad), None); + } + let mut policy = DeepsecPolicy::default(); + policy.ai_base_url = "https://user:password@example.com".into(); + assert!(policy.validate().is_err()); + assert!(DeepsecPolicy::default().validate().is_ok()); + } + #[test] + fn export_shape_has_positive_and_negative_controls() { + assert!(findings(b"[]").unwrap().is_empty()); + assert_eq!( + findings(br#"[{"filePath":"a","findings":[{"severity":"high"}]}]"#).unwrap()[0]["severity"], + "HIGH" + ); + for bad in [ + b"[null]".as_slice(), + b"{}", + b"[{\"severity\":\"SUPERHIGH\"}]", + b"[{\"findings\":[{}]}]", + b"[", + br#"[{"severity":"HIGH","severity":"LOW"}]"#, + br#"{"findings":[{"severity":"HIGH"}],"findings":[]}"#, + ] { + assert!(findings(bad).is_err()); + } + } +} diff --git a/src/deepsec_evidence.rs b/src/deepsec_evidence.rs new file mode 100644 index 0000000..790872c --- /dev/null +++ b/src/deepsec_evidence.rs @@ -0,0 +1,308 @@ +//! Private checks against the pinned reviewer's persisted protocol. +use super::{Attempt, DeepsecOptions, GateError, StrictJson, error, read_bounded, write_new}; +use crate::{Artifact, sha256}; +use serde_json::{Value, json}; +use std::collections::{BTreeMap, BTreeSet}; +use std::fs; +use std::path::{Path, PathBuf}; + +fn object(path: &Path) -> Result { + let bytes = read_bounded(path, 16 * 1024 * 1024)?; + serde_json::from_slice::(&bytes) + .map(|v| v.0) + .map_err(|_| error(70, "malformed reviewer state")) +} +fn confined(root: &Path, relative: &str) -> Result { + if !crate::relative_path(relative) + || relative.trim() != relative + || relative.contains(['\n', '\r', '\\']) + { + return Err(error( + 78, + "source path cannot be represented by the review protocol", + )); + } + let mut path = root.to_owned(); + for part in Path::new(relative).components() { + path.push(part); + if fs::symlink_metadata(&path) + .map_err(|_| error(70, "review source disappeared"))? + .file_type() + .is_symlink() + { + return Err(error(78, "review source must not traverse symlinks")); + } + } + Ok(path) +} +pub(super) fn snapshot(root: &Path, paths: &[String]) -> Result, GateError> { + if paths.len() > 100_000 { + return Err(error(78, "review file count exceeds 100000")); + } + let mut total = 0_usize; + paths + .iter() + .map(|name| { + let bytes = read_bounded(&confined(root, name)?, 32 * 1024 * 1024)?; + total = total.saturating_add(bytes.len()); + if total > 256 * 1024 * 1024 { + return Err(error( + 78, + "review source exceeds 256 MiB; choose a narrower scope", + )); + } + Ok(Artifact { + path: name.clone(), + sha256: sha256(&bytes), + }) + }) + .collect() +} +pub(super) fn select( + options: &DeepsecOptions, + files: Option<&Path>, + attempt: &mut Attempt<'_>, + root: &Path, +) -> Result, GateError> { + let raw = if let Some(files) = files { + if files == Path::new("-") { + let (rc, bytes) = attempt.command("input-files", "cat", vec![], root, false, true)?; + if rc != 0 { + return Err(error(78, "could not read file list")); + } + bytes + } else { + read_bounded(files, 8 * 1024 * 1024)? + } + } else { + let mut args: Vec = if options.full || options.scan_only { + vec![ + "ls-files", + "-z", + "--cached", + "--others", + "--exclude-standard", + ] + .into_iter() + .map(str::to_owned) + .collect() + } else { + vec!["diff", "--name-only", "-z", "--diff-filter=AMRC"] + .into_iter() + .map(str::to_owned) + .collect() + }; + if options.diff_staged { + args.push("--cached".into()); + } + if options.diff_working { + args.push("HEAD".into()); + } + if let Some(reference) = &options.diff { + if reference.starts_with('-') { + return Err(error(78, "diff reference must not be a Git option")); + } + args.push(reference.clone()); + } + args.push("--".into()); + let (rc, mut bytes) = + attempt.command("source-selection", "git", args, root, false, false)?; + if rc != 0 { + return Err(error(78, "could not resolve review source selection")); + } + if options.diff_working { + let (rc, more) = attempt.command( + "untracked-selection", + "git", + vec!["ls-files", "-z", "--others", "--exclude-standard", "--"] + .into_iter() + .map(str::to_owned) + .collect(), + root, + false, + false, + )?; + if rc != 0 { + return Err(error(78, "could not resolve untracked selection")); + } + bytes.extend(more); + } + bytes + }; + let text = String::from_utf8(raw).map_err(|_| error(78, "file list must be UTF-8"))?; + let separator = if files.is_some() { '\n' } else { '\0' }; + let paths: BTreeSet = text + .split(separator) + .filter(|s| !s.is_empty() && *s != ".deepsec-gate" && !s.starts_with(".deepsec-gate/")) + .map(str::to_owned) + .collect(); + if paths.is_empty() { + return Err(error( + 78, + "no review inputs; this is not a completed review", + )); + } + for path in &paths { + confined(root, path)?; + } + if options.diff_staged { + let (rc, bytes) = attempt.command( + "staged-byte-parity", + "git", + vec!["diff", "--name-only", "-z", "--"] + .into_iter() + .map(str::to_owned) + .collect(), + root, + false, + false, + )?; + let changed = String::from_utf8(bytes).map_err(|_| error(78, "Git paths must be UTF-8"))?; + if rc != 0 || changed.split('\0').any(|p| paths.contains(p)) { + return Err(error( + 78, + "staged inputs differ from working-tree bytes; review an exact index checkout", + )); + } + } + Ok(paths.into_iter().collect()) +} +pub(super) fn run_files(data: &Path) -> Result, GateError> { + let dir = data.join("runs"); + if !dir.exists() { + return Ok(BTreeSet::new()); + } + let meta = + fs::symlink_metadata(&dir).map_err(|_| error(70, "review run directory unavailable"))?; + if !meta.is_dir() || meta.file_type().is_symlink() { + return Err(error(70, "invalid review run directory")); + } + let mut set = BTreeSet::new(); + for item in fs::read_dir(dir).map_err(|_| error(70, "review runs cannot be read"))? { + let item = item.map_err(|_| error(70, "review run entry unavailable"))?; + if set.len() >= 100_000 { + return Err(error(70, "review history exceeds limit")); + } + if let Some(name) = item.file_name().to_str() { + if name.ends_with(".json") { + set.insert(name.to_owned()); + } + } + } + Ok(set) +} +fn file_record(data: &Path, name: &str) -> Result { + object(&confined(data, &format!("files/{name}.json"))?) +} +pub(super) fn pending(data: &Path, selected: &[Artifact]) -> Result, GateError> { + let mut out = Vec::new(); + for artifact in selected { + let path = data.join("files").join(format!("{}.json", artifact.path)); + if !path.exists() { + continue; + } + let value = file_record(data, &artifact.path)?; + if matches!( + value["status"].as_str(), + Some("pending" | "error" | "processing") + ) { + out.push(artifact.clone()); + } + } + if out.is_empty() { + return Err(error( + 78, + "scan has no pending candidates; no new review evidence produced", + )); + } + Ok(out) +} +pub(super) fn validate_review( + data: &Path, + prior: &BTreeSet, + expected: &[Artifact], + root: &Path, + project: &str, + report: &Path, +) -> Result { + let mut runs = Vec::new(); + for name in run_files(data)?.difference(prior) { + let value = object(&data.join("runs").join(name))?; + if value["type"] == "process" { + runs.push(value); + } + } + if runs.len() != 1 { + return Err(error(70, "missing or ambiguous fresh processing run")); + } + let run = &runs[0]; + let run_id = run["runId"] + .as_str() + .filter(|s| crate::identifier(s)) + .ok_or_else(|| error(70, "invalid processing run identity"))?; + if run["phase"] != "done" + || run["projectId"] != project + || run["rootPath"].as_str() != root.to_str() + || !run["completedAt"].is_string() + || run["stats"]["filesProcessed"].as_u64() != Some(expected.len() as u64) + { + return Err(error( + 70, + "processing run is incomplete or covers another scope", + )); + } + let mut records = BTreeMap::new(); + for artifact in expected { + let record = file_record(data, &artifact.path)?; + if record["filePath"] != artifact.path + || record["projectId"] != project + || record["fileHash"] != artifact.sha256 + || record["status"] != "analyzed" + { + return Err(error( + 70, + "review file identity, content or completion mismatch", + )); + } + let entries = record["analysisHistory"] + .as_array() + .ok_or_else(|| error(70, "missing per-file analysis history"))?; + let entries: Vec<_> = entries.iter().filter(|e| e["runId"] == run_id).collect(); + if entries.len() != 1 { + return Err(error( + 70, + "missing or ambiguous analysis for the current run", + )); + } + let entry = entries[0]; + if entry["refusal"]["refused"].as_bool() != Some(false) + || entry["refusal"]["skipped"] + .as_array() + .is_some_and(|s| !s.is_empty()) + { + return Err(error( + 70, + "review was refused, partly skipped, or refusal status is unknown", + )); + } + if entry["usage"]["outputTokens"] + .as_u64() + .is_none_or(|n| n == 0) + || entry["model"].as_str().is_none_or(|s| s.is_empty()) + || entry["agentType"].as_str().is_none_or(|s| s.is_empty()) + { + return Err(error( + 70, + "review lacks actual model identity or output evidence", + )); + } + records.insert(artifact.path.clone(), record); + } + let evidence = json!({"run":run,"files":records}); + let bytes = serde_json::to_vec_pretty(&evidence) + .map_err(|_| error(70, "review evidence encoding failed"))?; + write_new(&report.join("review-evidence.json"), &bytes)?; + Ok( + json!({"run_id":run_id,"observed_files":expected.iter().map(|a|&a.path).collect::>(),"evidence_sha256":sha256(&bytes),"coverage_boundary":"Recorded per-file investigations of exact selected bytes; dependencies and runtime behaviour remain outside this observation."}), + ) +} diff --git a/src/lib.rs b/src/lib.rs index fa60c8d..797b2f1 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -115,3 +115,11 @@ pub(crate) fn relative_path(path: &str) -> bool { }) .is_ok() } + +/// Bounded process execution with private evidence capture. +#[cfg(feature = "process")] +pub mod process; + +/// Versioned adapter for an independently installed Deepsec reviewer. +#[cfg(feature = "cli")] +pub mod deepsec; diff --git a/src/process.rs b/src/process.rs new file mode 100644 index 0000000..15bf144 --- /dev/null +++ b/src/process.rs @@ -0,0 +1,397 @@ +//! Bounded local command execution. This is a process runner, not a sandbox. +//! +//! Commands retain the invoking user's filesystem and network authority. Only +//! explicitly named environment variables are inherited. Captures are private +//! files; the runner never interprets their contents or shell metacharacters. + +use crate::plan::Invocation; +use std::fs::{self, File, OpenOptions}; +use std::io::{self, Read, Write}; +use std::path::{Path, PathBuf}; +use std::process::{Command, Stdio}; +use std::sync::Arc; +use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU64, Ordering}; +use std::thread; +use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH}; + +/// Why an invocation finished. A normal exit may still have a nonzero code. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Termination { + /// The process and both output streams completed. + Completed, + /// The executable could not be found. + Unavailable, + /// The executable could not be started for another reason. + FailedToStart, + /// The monotonic execution deadline expired. + TimedOut, + /// The caller requested cancellation. + Interrupted, + /// Capture was incomplete, exceeded its bound, or left descendants running. + CaptureFailed, +} + +/// Raw process observations; evaluator policy is applied separately. +#[derive(Debug)] +pub struct CapturedRun { + /// Observed termination, not a gate verdict. + pub termination: Termination, + /// Exit code where the operating system supplied one. + pub exit_code: Option, + /// Terminating Unix signal, if any. + pub signal: Option, + /// Start time as Unix milliseconds. + pub started_at_ms: u64, + /// End time as Unix milliseconds. + pub finished_at_ms: u64, + /// Elapsed monotonic time, in milliseconds. + pub elapsed_ms: u64, + /// Exact retained standard output. + pub stdout: PathBuf, + /// Exact retained standard error. + pub stderr: PathBuf, + /// Non-secret explanation of an incomplete attempt. + pub error: Option, +} + +fn unix_now() -> u64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .as_millis() + .try_into() + .unwrap_or(u64::MAX) +} + +/// Create a new private directory, refusing existing targets and symlink parents. +/// +/// The caller may canonicalise its explicitly selected workspace root first. +/// These checks do not sandbox a concurrently hostile filesystem. +pub fn private_directory(path: &Path) -> io::Result<()> { + let absolute = if path.is_absolute() { + path.to_owned() + } else { + std::env::current_dir()?.join(path) + }; + let mut current = PathBuf::new(); + for component in absolute.components() { + use std::path::Component; + match component { + Component::ParentDir => { + return Err(io::Error::new( + io::ErrorKind::InvalidInput, + "parent traversal in output path", + )); + } + Component::CurDir => continue, + _ => current.push(component), + } + if current == absolute { + break; + } + match fs::symlink_metadata(¤t) { + Ok(meta) if meta.is_dir() && !meta.file_type().is_symlink() => (), + Ok(_) => { + return Err(io::Error::new( + io::ErrorKind::InvalidInput, + "output parent is not an ordinary directory", + )); + } + Err(err) if err.kind() == io::ErrorKind::NotFound => { + let mut builder = fs::DirBuilder::new(); + #[cfg(unix)] + { + use std::os::unix::fs::DirBuilderExt; + builder.mode(0o700); + } + builder.create(¤t)?; + } + Err(err) => return Err(err), + } + } + let mut builder = fs::DirBuilder::new(); + #[cfg(unix)] + { + use std::os::unix::fs::DirBuilderExt; + builder.mode(0o700); + } + builder.create(&absolute) +} + +/// Exclusively create a private evidence file; existing files are never truncated. +pub fn private_file(path: &Path) -> io::Result { + let mut options = OpenOptions::new(); + options.write(true).create_new(true); + #[cfg(unix)] + { + use std::os::unix::fs::OpenOptionsExt; + options.mode(0o600); + } + options.open(path) +} + +#[cfg(unix)] +fn capture( + mut input: R, + mut output: File, + total: Arc, + fault: Arc, + stop: Arc, + limit: u64, +) -> thread::JoinHandle> { + thread::spawn(move || { + let result = (|| { + use nix::fcntl::{FcntlArg, OFlag, fcntl}; + let flags = fcntl(&input, FcntlArg::F_GETFL).map_err(io::Error::from)?; + fcntl( + &input, + FcntlArg::F_SETFL(OFlag::from_bits_truncate(flags) | OFlag::O_NONBLOCK), + ) + .map_err(io::Error::from)?; + let mut bytes = [0_u8; 8192]; + loop { + let count = match input.read(&mut bytes) { + Err(err) if err.kind() == io::ErrorKind::Interrupted => continue, + Err(err) if err.kind() == io::ErrorKind::WouldBlock => { + if stop.load(Ordering::SeqCst) { + return Err(io::Error::new( + io::ErrorKind::Interrupted, + "capture interrupted", + )); + } + thread::sleep(Duration::from_millis(5)); + continue; + } + other => other?, + }; + if count == 0 { + break; + } + let previous = total.fetch_add(count as u64, Ordering::SeqCst); + let allowed = limit.saturating_sub(previous).min(count as u64) as usize; + output.write_all(&bytes[..allowed])?; + if allowed != count { + fault.store(1, Ordering::SeqCst); + break; + } + } + output.sync_all() + })(); + if result.is_err() { + fault.store(2, Ordering::SeqCst); + } + result + }) +} + +#[cfg(unix)] +fn signal_group(pid: u32, signal: nix::sys::signal::Signal) { + if let Ok(pid) = i32::try_from(pid) { + if pid > 1 { + let _ = nix::sys::signal::killpg(nix::unistd::Pid::from_raw(pid), signal); + } + } +} + +/// Run one explicit invocation, retaining bounded stdout/stderr captures. +/// +/// `output` must be a fresh private directory created by the caller. Paths in +/// `Invocation::cwd` are resolved relative to `root`. The environment contains +/// only the named variables that exist in the caller. Stdin is closed unless +/// explicitly inherited for a transport such as Deepsec's `--files-from -`. +/// +/// Unix execution uses a new process group and stops that group on interruption, +/// deadline, capture failure or lingering descendants. Non-Unix execution is +/// explicitly unsupported rather than claiming unimplemented child cleanup. +pub fn run_command( + invocation: &Invocation, + root: &Path, + output: &Path, + cancelled: &AtomicBool, + inherit_stdin: bool, +) -> io::Result { + #[cfg(not(unix))] + { + let _ = (invocation, root, output, cancelled, inherit_stdin); + Err(io::Error::new( + io::ErrorKind::Unsupported, + "bounded process groups require Unix", + )) + } + #[cfg(unix)] + { + use nix::sys::signal::{Signal, killpg}; + use nix::unistd::Pid; + use std::os::unix::process::{CommandExt, ExitStatusExt}; + invocation.validate().map_err(|_| { + io::Error::new(io::ErrorKind::InvalidInput, "invalid invocation contract") + })?; + let started_at = unix_now(); + let start = Instant::now(); + let stdout_path = output.join("stdout.log"); + let stderr_path = output.join("stderr.log"); + let stdout_file = private_file(&stdout_path)?; + let stderr_file = private_file(&stderr_path)?; + let mut result = CapturedRun { + termination: Termination::FailedToStart, + exit_code: None, + signal: None, + started_at_ms: started_at, + finished_at_ms: started_at, + elapsed_ms: 0, + stdout: stdout_path, + stderr: stderr_path, + error: None, + }; + if cancelled.load(Ordering::SeqCst) { + result.termination = Termination::Interrupted; + result.error = Some("cancelled before invocation".into()); + return Ok(result); + } + if invocation.timeout_ms == 0 || invocation.max_output_bytes == 0 { + return Err(io::Error::new( + io::ErrorKind::InvalidInput, + "execution bounds must be positive", + )); + } + let cwd = root.join(&invocation.cwd); + let mut command = Command::new(&invocation.program); + command + .args(&invocation.args) + .current_dir(&cwd) + .env_clear() + .process_group(0) + .stdin(if inherit_stdin { + Stdio::inherit() + } else { + Stdio::null() + }) + .stdout(Stdio::piped()) + .stderr(Stdio::piped()); + for name in &invocation.env { + if let Some(value) = std::env::var_os(name) { + command.env(name, value); + } + } + let mut child = match command.spawn() { + Ok(child) => child, + Err(err) => { + result.termination = if err.kind() == io::ErrorKind::NotFound { + Termination::Unavailable + } else { + Termination::FailedToStart + }; + result.error = Some(format!("process start failed: {}", err.kind())); + result.finished_at_ms = unix_now(); + result.elapsed_ms = start.elapsed().as_millis().try_into().unwrap_or(u64::MAX); + return Ok(result); + } + }; + let pid = child.id(); + let total = Arc::new(AtomicU64::new(0)); + let fault = Arc::new(AtomicU8::new(0)); + let stop_capture = Arc::new(AtomicBool::new(false)); + let stdout = capture( + child.stdout.take().expect("piped stdout"), + stdout_file, + total.clone(), + fault.clone(), + stop_capture.clone(), + invocation.max_output_bytes, + ); + let stderr = capture( + child.stderr.take().expect("piped stderr"), + stderr_file, + total, + fault.clone(), + stop_capture.clone(), + invocation.max_output_bytes, + ); + let mut status = None; + result.termination = loop { + if cancelled.load(Ordering::SeqCst) { + break Termination::Interrupted; + } + if start.elapsed() >= Duration::from_millis(invocation.timeout_ms) { + break Termination::TimedOut; + } + if fault.load(Ordering::SeqCst) != 0 { + break Termination::CaptureFailed; + } + match child.try_wait() { + Ok(Some(exit)) => { + status = Some(exit); + break Termination::Completed; + } + Ok(None) => thread::sleep(Duration::from_millis(10)), + Err(_) => { + result.error = Some("could not observe process exit".into()); + break Termination::CaptureFailed; + } + } + }; + if result.termination == Termination::Completed { + // A completed parent must not strand background writers or spenders. + let group_alive = + i32::try_from(pid).is_ok_and(|p| p > 1 && killpg(Pid::from_raw(p), None).is_ok()); + if group_alive { + result.termination = Termination::CaptureFailed; + result.error = Some("process left unfinished descendants".into()); + } else { + // A slow filesystem flush is not evidence of a live descendant. + while !stdout.is_finished() || !stderr.is_finished() { + if cancelled.load(Ordering::SeqCst) { + result.termination = Termination::Interrupted; + break; + } + if start.elapsed() >= Duration::from_millis(invocation.timeout_ms) { + result.termination = Termination::TimedOut; + break; + } + thread::sleep(Duration::from_millis(5)); + } + } + } + if result.termination != Termination::Completed { + signal_group(pid, Signal::SIGINT); + let grace = Instant::now(); + while grace.elapsed() < Duration::from_millis(250) { + if status.is_none() { + status = child.try_wait().ok().flatten(); + } + if stdout.is_finished() && stderr.is_finished() && status.is_some() { + break; + } + thread::sleep(Duration::from_millis(10)); + } + signal_group(pid, Signal::SIGKILL); + stop_capture.store(true, Ordering::SeqCst); + } + if status.is_none() { + status = child.wait().ok(); + } + for capture in [stdout, stderr] { + if !matches!(capture.join(), Ok(Ok(()))) { + fault.store(2, Ordering::SeqCst); + } + } + if fault.load(Ordering::SeqCst) != 0 { + if result.termination == Termination::Completed { + result.termination = Termination::CaptureFailed; + } + result.error = Some( + if fault.load(Ordering::SeqCst) == 1 { + "output limit exceeded" + } else { + "capture failed" + } + .into(), + ); + } + result.exit_code = status.and_then(|s| s.code()); + result.signal = status.and_then(|s| s.signal()); + result.finished_at_ms = unix_now(); + result.elapsed_ms = start.elapsed().as_millis().try_into().unwrap_or(u64::MAX); + Ok(result) + } +} diff --git a/tests/deepsec.rs b/tests/deepsec.rs new file mode 100644 index 0000000..4a3b88b --- /dev/null +++ b/tests/deepsec.rs @@ -0,0 +1,207 @@ +//! External reviewer protocol controls using a model-free executable double. +#![cfg(all(unix, feature = "cli"))] +use serde_json::{Value, json}; +use std::fs; +use std::path::{Path, PathBuf}; +use std::process::{Command, Output}; +struct Fixture { + _temp: tempfile::TempDir, + root: PathBuf, + bin: PathBuf, + list: PathBuf, +} +impl Fixture { + fn new(case: &str) -> Self { + use std::os::unix::fs::PermissionsExt; + let temp = tempfile::tempdir().unwrap(); + let root = temp.path().join("repo"); + fs::create_dir(&root).unwrap(); + fs::write(root.join("input.py"), "print('safe fixture')\n").unwrap(); + fs::write(root.join(".fixture-case"), case).unwrap(); + for args in [ + vec!["init", "-q"], + vec!["add", "input.py"], + vec![ + "-c", + "user.name=Fixture", + "-c", + "user.email=fixture@example.invalid", + "commit", + "-qm", + "baseline", + ], + ] { + assert!( + Command::new("git") + .args(args) + .current_dir(&root) + .status() + .unwrap() + .success() + ); + } + let bin = temp.path().join("bin"); + fs::create_dir(&bin).unwrap(); + let fake = bin.join("deepsec"); + fs::write(&fake, include_bytes!("fixtures/deepsec.py")).unwrap(); + fs::set_permissions(fake, fs::Permissions::from_mode(0o700)).unwrap(); + let list = temp.path().join("files.txt"); + fs::write(&list, "input.py\n").unwrap(); + Self { + _temp: temp, + root, + bin, + list, + } + } + fn run(&self, mode: &[&str], policy: Value) -> Output { + let path = std::env::join_paths(std::iter::once(self.bin.clone()).chain( + std::env::split_paths(&std::env::var_os("PATH").unwrap_or_default()), + )) + .unwrap(); + Command::new(env!("CARGO_BIN_EXE_visioncraft")) + .arg("deepsec") + .args(mode) + .arg("--root") + .arg(&self.root) + .arg("--policy-json") + .arg(policy.to_string()) + .env("PATH", path) + .output() + .unwrap() + } + fn gate(&self) -> Output { + self.run( + &["--files-from", self.list.to_str().unwrap()], + json!({"max_duration":"10s"}), + ) + } + fn receipt(&self) -> Value { + let directory = fs::read_dir(self.root.join(".deepsec-gate/reports")) + .unwrap() + .next() + .unwrap() + .unwrap() + .path(); + serde_json::from_slice(&fs::read(directory.join("receipt.json")).unwrap()).unwrap() + } +} +#[test] +fn actual_review_and_threshold_have_positive_controls() { + for (case, code, result) in [ + ("pass", 0, "PASS"), + ("block", 1, "BLOCK"), + ("low", 0, "PASS"), + ] { + let f = Fixture::new(case); + let out = f.gate(); + assert_eq!( + out.status.code(), + Some(code), + "{case}: {} {}", + String::from_utf8_lossy(&out.stdout), + String::from_utf8_lossy(&out.stderr) + ); + let receipt = f.receipt(); + assert_eq!(receipt["result"], result); + assert_eq!( + receipt["observed_review"]["observed_files"], + json!(["input.py"]) + ); + } +} +#[test] +fn no_empty_partial_or_ambiguous_review_can_pass() { + for case in [ + "runtime", + "no-evidence", + "incomplete", + "refused", + "partial", + "unknown-refusal", + "zero-output", + "missing-model", + "stale", + "wrong-hash", + "drift", + "export-failure", + "malformed", + "duplicate-key", + ] { + let f = Fixture::new(case); + let out = f.gate(); + assert_eq!( + out.status.code(), + Some(70), + "{case}: {} {}", + String::from_utf8_lossy(&out.stdout), + String::from_utf8_lossy(&out.stderr) + ); + assert_eq!(f.receipt()["result"], "ERROR", "{case}"); + } +} +#[test] +fn unsupported_version_and_timeout_preserve_non_pass_states() { + let f = Fixture::new("unsupported"); + assert_eq!(f.gate().status.code(), Some(78)); + assert_eq!(f.receipt()["result"], "UNAVAILABLE"); + let f = Fixture::new("timeout"); + let out = f.run( + &["--files-from", f.list.to_str().unwrap()], + json!({"max_duration":"0.5s"}), + ); + assert_eq!(out.status.code(), Some(124)); + assert_eq!(f.receipt()["result"], "TIMEOUT"); +} +#[test] +fn scan_only_is_not_model_review_and_empty_scope_cannot_pass() { + let f = Fixture::new("pass"); + let out = f.run(&["--scan-only"], json!({})); + assert_eq!( + out.status.code(), + Some(0), + "{}", + String::from_utf8_lossy(&out.stderr) + ); + assert_eq!(f.receipt()["result"], "SCANNED"); + let f = Fixture::new("pass"); + fs::write(&f.list, "").unwrap(); + assert_eq!(f.gate().status.code(), Some(78)); +} +#[test] +fn staged_selection_must_match_reviewed_working_bytes() { + let f = Fixture::new("pass"); + fs::write(f.root.join("input.py"), "staged\n").unwrap(); + assert!( + Command::new("git") + .args(["add", "input.py"]) + .current_dir(&f.root) + .status() + .unwrap() + .success() + ); + fs::write(f.root.join("input.py"), "different\n").unwrap(); + let out = f.run(&["--diff-staged"], json!({})); + assert_eq!(out.status.code(), Some(78)); + assert!( + f.receipt()["error"] + .as_str() + .unwrap() + .contains("staged inputs") + ); +} +#[test] +fn dry_run_is_read_only_and_carries_names_not_credentials() { + let f = Fixture::new("pass"); + let out=f.run(&["--files-from",f.list.to_str().unwrap(),"--dry-run"],json!({"model_auth":"direct","ai_provider":"anthropic","ai_api_key_env":"FIXTURE_CREDENTIAL"})); + assert!(out.status.success()); + assert!(!f.root.join(".deepsec-gate").exists()); + let plan: Value = serde_json::from_slice(&out.stdout).unwrap(); + assert_eq!(plan["policy"]["ai_api_key_env"], "FIXTURE_CREDENTIAL"); + let out = f.run( + &["--files-from", f.list.to_str().unwrap(), "--dry-run"], + json!({"enabled":false}), + ); + assert_eq!(out.status.code(), Some(78)); + assert!(!f.root.join(".deepsec-gate").exists()); +} diff --git a/tests/fixtures/deepsec.py b/tests/fixtures/deepsec.py new file mode 100644 index 0000000..a68526e --- /dev/null +++ b/tests/fixtures/deepsec.py @@ -0,0 +1,52 @@ +#!/usr/bin/env python3 +"""Inert Deepsec 2.3.10 protocol double; never calls an LLM or a network.""" +import hashlib, json, pathlib, sys, time +args=sys.argv[1:] +def opt(name,default=None): + return args[args.index(name)+1] if name in args else default +workspace=pathlib.Path.cwd() +root=workspace.parent +casefile=root/'.fixture-case' +case=casefile.read_text().strip() if casefile.exists() else 'pass' +if args==['--version']: + print('9.0.0' if case=='unsupported' else '2.3.10');sys.exit(0) +project=opt('--project-id',root.name) +data=workspace/'data'/project +cmd=args[0] +if cmd=='scan': + target=data/'files'/'input.py.json';target.parent.mkdir(parents=True,exist_ok=True) + target.write_text(json.dumps({'filePath':'input.py','status':'pending'}));sys.exit(0) +if cmd=='process': + if case=='timeout':time.sleep(30) + if case=='runtime':sys.exit(1) + if case=='no-evidence':sys.exit(0) + paths=pathlib.Path(opt('--files-from')).read_text().splitlines() if '--files-from' in args else ['input.py'] + (data/'runs').mkdir(parents=True,exist_ok=True) + run_id='fixture-run' + run={'runId':run_id,'projectId':project,'rootPath':str(root),'type':'process','phase':'done','completedAt':'2026-11-03T00:00:00Z','stats':{'filesProcessed':len(paths)}} + if case=='incomplete':run['phase']='running' + (data/'runs'/f'{run_id}.json').write_text(json.dumps(run)) + for path in paths: + entry={'runId':run_id,'model':'fixture-model','agentType':'fixture-agent','refusal':{'refused':False},'usage':{'outputTokens':42}} + if case=='refused':entry['refusal']['refused']=True + if case=='partial':entry['refusal']['skipped']=[{'filePath':path,'reason':'fixture'}] + if case=='unknown-refusal':del entry['refusal'] + if case=='zero-output':entry['usage']['outputTokens']=0 + if case=='missing-model':del entry['model'] + record={'filePath':path,'projectId':project,'fileHash':hashlib.sha256((root/path).read_bytes()).hexdigest(),'status':'analyzed','analysisHistory':[entry]} + if case=='stale':record['analysisHistory'][0]['runId']='old-run' + if case=='wrong-hash':record['fileHash']='0'*64 + target=data/'files'/f'{path}.json';target.parent.mkdir(parents=True,exist_ok=True);target.write_text(json.dumps(record)) + if case=='drift':(root/'input.py').write_text('changed during review\n') + if case in ['block','low']: + pathlib.Path(opt('--comment-out')).write_text('Fresh finding\n');sys.exit(1) + sys.exit(0) +if cmd=='export': + if case=='export-failure':sys.exit(2) + output='[]' + if case=='malformed':output='{}' + if case=='duplicate-key':output='[{"severity":"HIGH","severity":"LOW"}]' + if case=='block':output='[{"severity":"HIGH","title":"fixture"}]' + if case=='low':output='[{"severity":"LOW","title":"fixture"}]' + pathlib.Path(opt('--out')).write_text(output);sys.exit(0) +sys.exit(99) diff --git a/tests/process.rs b/tests/process.rs new file mode 100644 index 0000000..ea3897f --- /dev/null +++ b/tests/process.rs @@ -0,0 +1,171 @@ +//! Executable process-boundary controls. +#![cfg(all(unix, feature = "process"))] + +use std::fs; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::time::{Duration, Instant}; +use visioncraft::Invocation; +use visioncraft::process::{Termination, private_directory, run_command}; + +fn invocation(script: &str) -> Invocation { + Invocation { + program: "sh".into(), + args: vec!["-c".into(), script.into()], + cwd: ".".into(), + env: vec!["PATH".into()], + timeout_ms: 2_000, + max_output_bytes: 8192, + } +} + +#[test] +fn argv_remains_literal_and_only_named_environment_is_inherited() { + let root = tempfile::tempdir().unwrap(); + let out = root.path().join("attempt"); + private_directory(&out).unwrap(); + let mut spec = invocation("printf '%s\\n' \"$1\"; printf '%s' \"${HOME-unset}\" >&2"); + let literal = "$(touch SHOULD_NOT_EXIST); `echo secret`"; + spec.args.extend(["fixture".into(), literal.into()]); + let result = run_command(&spec, root.path(), &out, &AtomicBool::new(false), false).unwrap(); + assert_eq!(result.termination, Termination::Completed, "{result:?}"); + assert_eq!(result.exit_code, Some(0)); + assert_eq!( + fs::read_to_string(result.stdout).unwrap(), + format!("{literal}\n") + ); + assert_eq!(fs::read_to_string(result.stderr).unwrap(), "unset"); + assert!(!root.path().join("SHOULD_NOT_EXIST").exists()); +} + +#[test] +fn exit_code_is_observed_without_being_relabelled_as_process_failure() { + let root = tempfile::tempdir().unwrap(); + let out = root.path().join("attempt"); + private_directory(&out).unwrap(); + let result = run_command( + &invocation("printf 'assertion reached' >&2; exit 9"), + root.path(), + &out, + &AtomicBool::new(false), + false, + ) + .unwrap(); + assert_eq!(result.termination, Termination::Completed, "{result:?}"); + assert_eq!(result.exit_code, Some(9)); + assert_eq!( + fs::read_to_string(result.stderr).unwrap(), + "assertion reached" + ); +} + +#[test] +fn timeout_stops_a_descendant_and_preserves_partial_output() { + let root = tempfile::tempdir().unwrap(); + let out = root.path().join("attempt"); + private_directory(&out).unwrap(); + let mut spec = invocation("sleep 30 & printf '%s' \"$!\"; wait"); + spec.timeout_ms = 100; + let start = Instant::now(); + let result = run_command(&spec, root.path(), &out, &AtomicBool::new(false), false).unwrap(); + assert_eq!(result.termination, Termination::TimedOut); + assert!(start.elapsed() < Duration::from_secs(3)); + let pid = fs::read_to_string(result.stdout).unwrap(); + #[cfg(target_os = "linux")] + if let Ok(stat) = fs::read_to_string(format!("/proc/{pid}/stat")) { + // An orphan may await the container's reaper; it must no longer execute. + let state = stat + .rsplit_once(") ") + .unwrap() + .1 + .split_whitespace() + .next() + .unwrap(); + assert_eq!(state, "Z", "descendant still running: {stat}"); + } +} + +#[test] +fn output_limit_and_lingering_background_processes_cannot_pass() { + let root = tempfile::tempdir().unwrap(); + let out = root.path().join("overflow"); + private_directory(&out).unwrap(); + let mut spec = invocation("yes output"); + spec.max_output_bytes = 1024; + let result = run_command(&spec, root.path(), &out, &AtomicBool::new(false), false).unwrap(); + assert_eq!(result.termination, Termination::CaptureFailed); + assert!( + fs::metadata(result.stdout).unwrap().len() + fs::metadata(result.stderr).unwrap().len() + <= 1024 + ); + let out = root.path().join("background"); + private_directory(&out).unwrap(); + let result = run_command( + &invocation("sleep 30 & exit 0"), + root.path(), + &out, + &AtomicBool::new(false), + false, + ) + .unwrap(); + assert_eq!(result.termination, Termination::CaptureFailed); +} + +#[test] +fn cancellation_and_missing_program_are_explicit() { + let root = tempfile::tempdir().unwrap(); + let out = root.path().join("missing"); + private_directory(&out).unwrap(); + let mut spec = invocation("exit 0"); + spec.program = "visioncraft-no-such-program-20261103".into(); + let result = run_command(&spec, root.path(), &out, &AtomicBool::new(false), false).unwrap(); + assert_eq!(result.termination, Termination::Unavailable); + let out = root.path().join("cancelled"); + private_directory(&out).unwrap(); + let cancelled = AtomicBool::new(false); + std::thread::scope(|scope| { + scope.spawn(|| { + std::thread::sleep(Duration::from_millis(60)); + cancelled.store(true, Ordering::SeqCst); + }); + let result = run_command( + &invocation("sleep 30"), + root.path(), + &out, + &cancelled, + false, + ) + .unwrap(); + assert_eq!(result.termination, Termination::Interrupted); + }); +} + +#[test] +fn private_output_is_fresh_and_does_not_follow_symlinks() { + use std::os::unix::fs::{PermissionsExt, symlink}; + let root = tempfile::tempdir().unwrap(); + let out = root.path().join("attempt"); + private_directory(&out).unwrap(); + assert_eq!( + fs::metadata(&out).unwrap().permissions().mode() & 0o777, + 0o700 + ); + assert!(private_directory(&out).is_err()); + let other = tempfile::tempdir().unwrap(); + symlink(other.path(), root.path().join("foreign")).unwrap(); + assert!(private_directory(&root.path().join("foreign/new")).is_err()); + assert!(!other.path().join("new").exists()); + let victim = other.path().join("victim"); + fs::write(&victim, "unchanged").unwrap(); + symlink(&victim, out.join("stdout.log")).unwrap(); + assert!( + run_command( + &invocation("printf altered"), + root.path(), + &out, + &AtomicBool::new(false), + false + ) + .is_err() + ); + assert_eq!(fs::read_to_string(victim).unwrap(), "unchanged"); +} From 821658b4353bcb8b053c0774589a92c58fd4aeae Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 3 Nov 2026 11:01:12 +0000 Subject: [PATCH 05/16] Add native plan capture execution and evidence evaluation commands --- src/cli.rs | 989 ++++++++++++++++++++++++++++++++++++++++++++ src/main.rs | 38 ++ tests/native_cli.rs | 406 ++++++++++++++++++ 3 files changed, 1433 insertions(+) create mode 100644 src/cli.rs create mode 100644 src/main.rs create mode 100644 tests/native_cli.rs diff --git a/src/cli.rs b/src/cli.rs new file mode 100644 index 0000000..a8c5169 --- /dev/null +++ b/src/cli.rs @@ -0,0 +1,989 @@ +//! Native filesystem and command-line adapter for the deterministic core. +//! +//! Evaluation only reads source and evidence plus fixed Git metadata commands. +//! Commands in imported receipts are never replayed. All source coverage and test +//! observations remain unknown unless supplied by an actual observer/adapter. + +use std::collections::BTreeSet; +use std::fs::{self, File}; +use std::io::{Read, Write}; +use std::path::{Component, Path, PathBuf}; +use std::process::{Command, Stdio}; +use std::sync::atomic::AtomicBool; +use std::time::{SystemTime, UNIX_EPOCH}; + +use crate::process::{self, Termination}; +use crate::{ + Artifact, AuditReceipt, CheckSpec, Evaluator, ExecutionReceipt, GateOutcome, GatePolicy, + Invocation, ManualObservation, ProcessStatus, QualityPlan, Subject, VerifiedArtifacts, +}; +use clap::{Args, Parser, Subcommand}; +use serde::{Deserialize, Serialize}; + +const MAX_JSON: u64 = 64 * 1024 * 1024; +const MAX_FILE: u64 = 1024 * 1024 * 1024; + +/// Explicit quality operations; only `run` and `deepsec` execute supplied checks. +#[derive(Debug, Parser)] +#[command( + name = "visioncraft", + version, + about = "Explicit quality checks and evidence-bound gates" +)] +pub struct Cli { + #[command(subcommand)] + command: Operation, +} + +#[derive(Debug, Subcommand)] +enum Operation { + /// Capture or validate a quality plan without running its check commands. + Plan { + #[command(subcommand)] + command: PlanCommand, + }, + /// Execute selected exit-code checks and retain private receipts. + Run(RunOptions), + /// Evaluate existing receipts; never execute their recorded commands. + Evaluate(EvaluateOptions), + /// Evaluate the whole required-check gate. + Gate { + #[command(subcommand)] + command: GateCommand, + }, + /// Check expectation coverage and all other required checks together. + Expectations { + #[command(subcommand)] + command: ExpectationCommand, + }, + /// Run the versioned Deepsec security adapter. + Deepsec(crate::deepsec::DeepsecOptions), +} + +#[derive(Debug, Subcommand)] +enum PlanCommand { + /// Capture selected source bytes into a plan for one explicit argv check. + Init(InitOptions), + /// Validate a plan schema and policy; no recorded commands are run. + Check { + plan: PathBuf, + #[arg(long)] + json: bool, + }, +} + +#[derive(Debug, Subcommand)] +enum GateCommand { + Evaluate(EvaluateOptions), +} + +#[derive(Debug, Subcommand)] +enum ExpectationCommand { + Check(EvaluateOptions), +} + +#[derive(Debug, Args)] +struct InitOptions { + /// Explicit Git worktree root; defaults to the current directory. + #[arg(long, default_value = ".")] + root: PathBuf, + /// New plan file; existing outputs are refused. + #[arg(long)] + out: PathBuf, + /// Selected source paths relative to root; repeat for locks/configuration. + #[arg(long, required = true)] + input: Vec, + #[arg(long, default_value = "quality")] + id: String, + #[arg(long, default_value = "check")] + check: String, + #[arg(long)] + repository: Option, + /// Features, target and fixture relevant to this check. + #[arg(long)] + configuration: String, + #[arg(long, default_value = ".")] + cwd: String, + /// Inherited environment names only; never values. + #[arg(long, default_value = "PATH")] + env: Vec, + #[arg(long, default_value_t = 60_000)] + timeout_ms: u64, + #[arg(long, default_value_t = 8 * 1024 * 1024)] + max_output_bytes: u64, + /// Literal program and arguments after `--`; no shell is added. + #[arg(last = true, required = true, num_args = 1..)] + command: Vec, +} + +#[derive(Debug, Args)] +#[command(group(clap::ArgGroup::new("selection").required(true).multiple(false).args(["check", "all"])))] +struct RunOptions { + plan: PathBuf, + #[arg(long, default_value = ".")] + root: PathBuf, + /// Select a single declared check. + #[arg(long)] + check: Option, + /// Run every declared check serially. + #[arg(long)] + all: bool, + /// Fresh private run directory; never reuse an earlier attempt. + #[arg(long)] + out: PathBuf, +} + +#[derive(Debug, Args)] +struct EvaluateOptions { + plan: PathBuf, + #[arg(long, default_value = ".")] + root: PathBuf, + /// Run root containing check-*/receipt.json and their relative artifacts. + #[arg(long, required = true)] + receipts: Vec, + /// Optional strict JSON audit/manual/family context; artifact paths are + /// relative to this file's parent, which must be a private evidence root. + #[arg(long)] + context: Option, + /// Optional current-subject JSON, verified against the actual selected files. + #[arg(long)] + current_subject: Option, + /// Inject evaluation time in Unix milliseconds; defaults to the current clock. + #[arg(long)] + as_of_ms: Option, + #[arg(long)] + json: bool, +} + +#[derive(Debug, Default, Deserialize)] +#[serde(deny_unknown_fields)] +struct ContextFile { + #[serde(default)] + audits: Vec, + #[serde(default)] + manual_observations: Vec, + #[serde(default)] + families: Vec, +} + +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields)] +struct FamilyDeclaration { + route: String, + family: String, +} + +/// CLI failure with a stable process exit code and non-source diagnostic. +#[derive(Debug, thiserror::Error)] +#[error("{message}")] +pub struct CliError { + /// Usage/schema (2), execution (70), unavailable (78), timeout (124), etc. + pub code: i32, + /// Diagnostic without raw source/configuration contents. + pub message: String, +} + +fn error(code: i32, message: impl Into) -> CliError { + CliError { + code, + message: message.into(), + } +} +fn invalid(e: impl std::fmt::Display) -> CliError { + error(2, e.to_string()) +} +fn io_error(e: std::io::Error) -> CliError { + error( + 70, + format!("filesystem/process operation failed: {}", e.kind()), + ) +} + +fn now_ms() -> u64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .as_millis() + .try_into() + .unwrap_or(u64::MAX) +} + +fn root(path: &Path) -> Result { + let path = path.canonicalize().map_err(io_error)?; + if !path.is_dir() { + return Err(error(2, "root must be a directory")); + } + Ok(path) +} + +fn confined(root: &Path, relative: &str, directory: bool) -> Result { + if relative == "." && directory { + return Ok(root.to_owned()); + } + if !crate::relative_path(relative) { + return Err(error(2, "path must be confined and relative")); + } + let mut path = root.to_owned(); + for component in Path::new(relative).components() { + let Component::Normal(name) = component else { + return Err(error(2, "invalid relative path")); + }; + path.push(name); + let metadata = fs::symlink_metadata(&path).map_err(io_error)?; + if metadata.file_type().is_symlink() { + return Err(error( + 2, + "symlinks inside source/evidence roots are refused", + )); + } + } + let metadata = fs::metadata(&path).map_err(io_error)?; + if (directory && !metadata.is_dir()) || (!directory && !metadata.is_file()) { + return Err(error(2, "expected an ordinary file or directory")); + } + Ok(path) +} + +fn read_bounded(path: &Path, limit: u64) -> Result, CliError> { + let metadata = fs::symlink_metadata(path).map_err(io_error)?; + if !metadata.is_file() || metadata.file_type().is_symlink() { + return Err(error(2, "only ordinary files may be read")); + } + if metadata.len() > limit { + return Err(error(2, "input exceeds the bounded file size")); + } + let mut bytes = Vec::new(); + File::open(path) + .map_err(io_error)? + .take(limit + 1) + .read_to_end(&mut bytes) + .map_err(io_error)?; + if bytes.len() as u64 > limit { + return Err(error(2, "input exceeds the bounded file size")); + } + Ok(bytes) +} + +fn read_explicit(path: &Path, limit: u64) -> Result<(PathBuf, Vec), CliError> { + let parent = root( + path.parent() + .filter(|p| !p.as_os_str().is_empty()) + .unwrap_or(Path::new(".")), + )?; + let name = path + .file_name() + .and_then(|x| x.to_str()) + .ok_or_else(|| error(2, "input filename must be UTF-8"))?; + let file = confined(&parent, name, false)?; + Ok((parent, read_bounded(&file, limit)?)) +} + +fn output_path(path: &Path) -> Result { + let absolute = if path.is_absolute() { + path.to_owned() + } else { + std::env::current_dir().map_err(io_error)?.join(path) + }; + let mut current = PathBuf::new(); + for component in absolute.components() { + match component { + Component::ParentDir => return Err(error(2, "output path cannot traverse parents")), + Component::CurDir => continue, + _ => current.push(component), + } + match fs::symlink_metadata(¤t) { + Ok(m) if m.file_type().is_symlink() => { + return Err(error(2, "symlinked output paths are refused")); + } + Ok(_) if current == absolute => return Err(error(2, "output already exists")), + Ok(m) if m.is_dir() => {} + Ok(_) => return Err(error(2, "output parent is not a directory")), + Err(e) if e.kind() == std::io::ErrorKind::NotFound && current == absolute => {} + Err(e) => return Err(io_error(e)), + } + } + Ok(absolute) +} + +fn write_new(path: &Path, bytes: &[u8]) -> Result<(), CliError> { + let path = output_path(path)?; + let parent = path + .parent() + .ok_or_else(|| error(2, "output lacks parent"))?; + let mut temporary = tempfile::NamedTempFile::new_in(parent).map_err(io_error)?; + temporary.write_all(bytes).map_err(io_error)?; + temporary.as_file().sync_all().map_err(io_error)?; + temporary + .persist_noclobber(&path) + .map_err(|e| io_error(e.error))?; + Ok(()) +} + +fn json_bytes(value: &impl Serialize) -> Result, CliError> { + let mut bytes = serde_json::to_vec_pretty(value).map_err(invalid)?; + bytes.push(b'\n'); + Ok(bytes) +} + +fn print_json(value: &impl Serialize) -> Result<(), CliError> { + std::io::stdout() + .write_all(&json_bytes(value)?) + .map_err(io_error) +} + +fn git(root: &Path, args: &[&str]) -> Result { + Command::new("git") + .args([ + "--no-pager", + "--literal-pathspecs", + "-c", + "core.fsmonitor=false", + "-c", + "core.untrackedCache=false", + "-C", + ]) + .arg(root) + .args(args) + .env("GIT_OPTIONAL_LOCKS", "0") + .env("GIT_NO_LAZY_FETCH", "1") + .env("GIT_NO_REPLACE_OBJECTS", "1") + .env("GIT_TERMINAL_PROMPT", "0") + .stdin(Stdio::null()) + .output() + .map_err(io_error) +} + +fn revision(root: &Path) -> Result { + let output = git(root, &["rev-parse", "--verify", "HEAD"])?; + let revision = String::from_utf8(output.stdout) + .map_err(|_| error(2, "Git revision is not UTF-8"))? + .trim() + .to_owned(); + if !output.status.success() || !crate::hex(&revision, &[40, 64]) { + return Err(error(2, "source root requires a committed Git revision")); + } + Ok(revision) +} + +fn selected_dirty(root: &Path, paths: &[String]) -> Result { + // Git status/diff may invoke configured clean filters. Compare unfiltered + // committed blob bytes instead; worktree conversion differences are dirty. + let mut args = vec!["ls-tree", "-z", "--full-tree", "HEAD", "--"]; + args.extend(paths.iter().map(String::as_str)); + let output = git(root, &args)?; + if !output.status.success() { + return Err(error(70, "could not inspect selected Git input status")); + } + let mut entries = std::collections::BTreeMap::new(); + for row in output + .stdout + .split(|b| *b == 0) + .filter(|row| !row.is_empty()) + { + let (meta, path) = row.split_at( + row.iter() + .position(|b| *b == b'\t') + .ok_or_else(|| error(70, "invalid Git tree record"))?, + ); + let meta = std::str::from_utf8(meta).map_err(|_| error(70, "invalid Git tree metadata"))?; + let fields: Vec<_> = meta.split_whitespace().collect(); + if fields.len() != 3 || fields[1] != "blob" { + continue; + } + let path = std::str::from_utf8(&path[1..]) + .map_err(|_| error(70, "selected Git path is not UTF-8"))?; + entries.insert(path.to_owned(), fields[2].to_owned()); + } + for path in paths { + let Some(object) = entries.get(path) else { + return Ok(true); + }; + if !crate::hex(object, &[40, 64]) { + return Err(error(70, "invalid Git object identifier")); + } + let blob = git(root, &["cat-file", "blob", object])?; + if !blob.status.success() { + return Err(error(70, "committed source blob is unavailable")); + } + let current = match confined(root, path, false) { + Ok(file) => read_bounded(&file, MAX_FILE)?, + Err(_) if !root.join(path).try_exists().map_err(io_error)? => return Ok(true), + Err(e) => return Err(e), + }; + if blob.stdout != current { + return Ok(true); + } + } + Ok(false) +} + +#[derive(Serialize)] +struct SnapshotInput { + path: String, + sha256: String, + bytes: Vec, +} + +fn inputs(root: &Path, paths: &[String], missing_ok: bool) -> Result, CliError> { + let mut result = Vec::new(); + for path in paths { + match confined(root, path, false) { + Ok(file) => result.push(Artifact { + path: path.clone(), + sha256: crate::sha256(&read_bounded(&file, MAX_FILE)?), + }), + Err(_) if missing_ok && !root.join(path).try_exists().map_err(io_error)? => { + // Re-walk existing parents to distinguish deletion from a symlink + // escape or an unreadable path. Only NotFound is an omission. + let mut p = root.to_owned(); + for c in Path::new(path).components() { + p.push(c); + match fs::symlink_metadata(&p) { + Err(e) if e.kind() == std::io::ErrorKind::NotFound => break, + Err(e) => return Err(io_error(e)), + Ok(m) if m.file_type().is_symlink() => { + return Err(error(2, "symlinked input refused")); + } + _ => {} + } + } + } + Err(e) => return Err(e), + } + } + Ok(result) +} + +fn source_snapshot( + root: &Path, + paths: &[String], + revision: &str, + expected: &[Artifact], +) -> Result, CliError> { + let mut files = Vec::new(); + let mut total = 0usize; + for path in paths { + let bytes = read_bounded(&confined(root, path, false)?, MAX_JSON)?; + total = total.saturating_add(bytes.len()); + if total > (MAX_JSON / 5) as usize { + return Err(error( + 2, + "dirty selected inputs exceed private snapshot bound", + )); + } + let digest = crate::sha256(&bytes); + if !expected + .iter() + .any(|a| &a.path == path && a.sha256 == digest) + { + return Err(error( + 1, + "selected inputs changed while capturing the dirty snapshot", + )); + } + files.push(SnapshotInput { + path: path.clone(), + sha256: digest, + bytes, + }); + } + json_bytes(&serde_json::json!({"revision":revision,"selected_inputs":files})) +} + +fn read_plan(path: &Path) -> Result<(PathBuf, QualityPlan), CliError> { + let (parent, bytes) = read_explicit(path, MAX_JSON)?; + Ok((parent, QualityPlan::parse(&bytes).map_err(invalid)?)) +} + +fn init(options: InitOptions) -> Result { + let root = root(&options.root)?; + let out = output_path(&options.out)?; + let mut paths = options.input; + paths.sort(); + if paths.windows(2).any(|p| p[0] == p[1]) { + return Err(error(2, "input paths must be unique")); + } + for path in &paths { + if !crate::relative_path(path) { + return Err(error(2, "input paths must be relative")); + } + } + let revision = revision(&root)?; + let selected = inputs(&root, &paths, false)?; + let dirty = selected_dirty(&root, &paths)?; + let snapshot = if dirty { + Some(source_snapshot(&root, &paths, &revision, &selected)?) + } else { + None + }; + let snapshot_directory = format!( + ".{}.evidence", + out.file_name() + .and_then(|p| p.to_str()) + .ok_or_else(|| error(2, "plan filename must be UTF-8"))? + ); + let snapshot_name = format!("{snapshot_directory}/selected-inputs.json"); + let working_tree = snapshot.as_ref().map(|bytes| Artifact { + path: snapshot_name.clone(), + sha256: crate::sha256(bytes), + }); + let plan = QualityPlan { + version: 1, + id: options.id, + subject: Subject { + repository: options.repository.unwrap_or_else(|| { + root.file_name() + .unwrap_or_default() + .to_string_lossy() + .into_owned() + }), + revision, + configuration: options.configuration, + dirty, + working_tree, + inputs: selected, + }, + checks: vec![CheckSpec { + id: options.check, + required: true, + invocation: Invocation { + program: options.command[0].clone(), + args: options.command[1..].to_vec(), + cwd: options.cwd, + env: options.env, + timeout_ms: options.timeout_ms, + max_output_bytes: options.max_output_bytes, + }, + evaluator: Evaluator::ExitCode { + success_codes: vec![0], + }, + scope: paths.clone(), + }], + expectations: vec![], + policy: GatePolicy { + max_age_ms: Some(30 * 24 * 60 * 60 * 1000), + require_observed_scope: false, + }, + }; + plan.validate().map_err(invalid)?; + confined(&root, &plan.checks[0].invocation.cwd, true)?; + if inputs(&root, &paths, false)? != plan.subject.inputs { + return Err(error(1, "selected inputs changed while preparing the plan")); + } + if let Some(bytes) = &snapshot { + let parent = out.parent().ok_or_else(|| error(2, "plan needs parent"))?; + let snapshot_root = parent.join(&snapshot_directory); + process::private_directory(&snapshot_root).map_err(io_error)?; + write_new(&snapshot_root.join(".gitignore"), b"*\n")?; + let snapshot_path = parent.join(&snapshot_name); + write_new(&snapshot_path, bytes)?; + } + write_new(&out, &json_bytes(&plan)?)?; + print_json( + &serde_json::json!({"operation":"plan-init","plan":out,"plan_sha256":plan.digest().map_err(invalid)?,"check_commands_executed":false,"selected_inputs":paths.len()}), + )?; + Ok(0) +} + +fn add_artifact( + verified: &mut VerifiedArtifacts, + root: &Path, + artifact: &Artifact, +) -> Result<(), CliError> { + crate::artifact_shape(artifact).map_err(invalid)?; + let bytes = read_bounded(&confined(root, &artifact.path, false)?, MAX_FILE)?; + verified.insert(artifact, &bytes).map_err(invalid) +} + +fn receipt_artifacts(receipt: &ExecutionReceipt) -> Vec<&Artifact> { + receipt + .stdout + .iter() + .chain(receipt.stderr.iter()) + .chain(receipt.subject.working_tree.iter()) + .chain(receipt.reported.iter().map(|r| &r.artifact)) + .collect() +} + +fn evidence_parent(root: &Path, path: &str) -> Result { + if !crate::relative_path(path) { + return Err(error(2, "artifact output path is not confined")); + } + let path = root.join(path); + if let Some(parent) = path.parent() { + if !parent.exists() { + process::private_directory(parent).map_err(io_error)?; + } + } + output_path(&path) +} + +fn process_status(termination: Termination) -> ProcessStatus { + match termination { + Termination::Completed => ProcessStatus::Completed, + Termination::Unavailable => ProcessStatus::Unavailable, + Termination::FailedToStart => ProcessStatus::FailedToStart, + Termination::TimedOut => ProcessStatus::TimedOut, + Termination::Interrupted => ProcessStatus::Interrupted, + Termination::CaptureFailed => ProcessStatus::CaptureFailed, + } +} + +fn execution_exit(receipt: &ExecutionReceipt, evaluator: &Evaluator) -> i32 { + match receipt.process { + ProcessStatus::Unavailable => 78, + ProcessStatus::TimedOut => 124, + ProcessStatus::Interrupted => 130, + ProcessStatus::FailedToStart | ProcessStatus::CaptureFailed => 70, + ProcessStatus::Completed => match evaluator { + Evaluator::ExitCode { success_codes } + if receipt + .exit_code + .is_some_and(|code| success_codes.contains(&code)) => + { + 0 + } + _ => 1, + }, + } +} + +fn run(options: RunOptions, cancelled: &AtomicBool) -> Result { + let source_root = root(&options.root)?; + let (plan_root, plan) = read_plan(&options.plan)?; + let selected: Vec<_> = plan + .checks + .iter() + .filter(|c| options.all || options.check.as_deref() == Some(&c.id)) + .collect(); + if selected.is_empty() { + return Err(error(2, "selected check does not exist")); + } + for check in &selected { + if !matches!(check.evaluator, Evaluator::ExitCode { .. }) { + return Err(error( + 78, + "reported evaluators require their named adapter; generic run cannot invent an assessment", + )); + } + confined(&source_root, &check.invocation.cwd, true)?; + } + let paths: Vec<_> = plan.subject.inputs.iter().map(|a| a.path.clone()).collect(); + if revision(&source_root)? != plan.subject.revision + || inputs(&source_root, &paths, false)? != plan.subject.inputs + { + return Err(error( + 1, + "current selected source does not match the plan; create a new plan", + )); + } + let mut snapshot_bytes = None; + if let Some(snapshot) = &plan.subject.working_tree { + let bytes = read_bounded(&confined(&plan_root, &snapshot.path, false)?, MAX_JSON)?; + if crate::sha256(&bytes) != snapshot.sha256 { + return Err(error(2, "dirty snapshot hash does not match the plan")); + } + snapshot_bytes = Some(bytes); + } + process::private_directory(&options.out).map_err(io_error)?; + let out = root(&options.out)?; + write_new(&out.join(".gitignore"), b"*\n")?; + write_new(&out.join("plan.json"), &json_bytes(&plan)?)?; + if let (Some(snapshot), Some(bytes)) = (&plan.subject.working_tree, snapshot_bytes) { + write_new(&evidence_parent(&out, &snapshot.path)?, &bytes)?; + } + let mut receipts = Vec::new(); + let mut exit = 0; + for (index, check) in selected.into_iter().enumerate() { + if inputs(&source_root, &paths, false)? != plan.subject.inputs + || revision(&source_root)? != plan.subject.revision + { + return Err(error( + 1, + "selected inputs changed before a later check; previous receipts retained", + )); + } + confined(&source_root, &check.invocation.cwd, true)?; + let directory = format!("check-{index:04}"); + let attempt = out.join(&directory); + process::private_directory(&attempt).map_err(io_error)?; + let captured = + process::run_command(&check.invocation, &source_root, &attempt, cancelled, false) + .map_err(io_error)?; + let stdout = Artifact { + path: format!("{directory}/stdout.log"), + sha256: crate::sha256(&read_bounded(&captured.stdout, MAX_FILE)?), + }; + let stderr = Artifact { + path: format!("{directory}/stderr.log"), + sha256: crate::sha256(&read_bounded(&captured.stderr, MAX_FILE)?), + }; + let mut status = process_status(captured.termination); + let mut diagnostic = captured.error; + if status == ProcessStatus::Completed && captured.signal.is_some() { + status = ProcessStatus::Interrupted; + diagnostic = Some("process terminated by a signal".into()); + } + let after = match inputs(&source_root, &paths, true) { + Ok(after) => after, + Err(_) => { + status = ProcessStatus::CaptureFailed; + diagnostic = Some("could not capture selected inputs after execution".into()); + vec![] + } + }; + if status != ProcessStatus::Completed && diagnostic.is_none() { + diagnostic = Some(format!("execution ended as {status:?}")); + } + let receipt = ExecutionReceipt { + version: 1, + attempt_id: format!( + "{}-{}-{}", + check.id, + captured.started_at_ms, + std::process::id() + ), + plan_sha256: plan.digest().map_err(invalid)?, + check_id: check.id.clone(), + subject: plan.subject.clone(), + invocation: check.invocation.clone(), + executable: check.invocation.program.clone(), + executable_sha256: None, + tool_version: None, + started_at_ms: captured.started_at_ms, + finished_at_ms: captured.finished_at_ms, + elapsed_ms: captured.elapsed_ms, + process: status, + exit_code: captured.exit_code, + signal: captured.signal, + capture_complete: status == ProcessStatus::Completed, + stdout: Some(stdout), + stderr: Some(stderr), + inputs_after: after, + observed_scope: None, + observed_tests: vec![], + reported: None, + diagnostic, + }; + receipt.validate().map_err(invalid)?; + let path = attempt.join("receipt.json"); + write_new(&path, &json_bytes(&receipt)?)?; + let code = execution_exit(&receipt, &check.evaluator); + if exit == 0 && code != 0 { + exit = code; + } + if receipt.inputs_after != plan.subject.inputs && exit == 0 { + exit = 1; + } + receipts.push(path); + if receipt.process != ProcessStatus::Completed { + break; + } + } + print_json( + &serde_json::json!({"operation":"run","gate_evaluated":false,"receipts":receipts,"exit":exit}), + )?; + Ok(exit) +} + +fn load_receipts( + directory: &Path, + verified: &mut VerifiedArtifacts, +) -> Result, CliError> { + let root = root(directory)?; + let mut paths = Vec::new(); + for entry in fs::read_dir(&root).map_err(io_error)? { + let entry = entry.map_err(io_error)?; + let name = entry.file_name().to_string_lossy().into_owned(); + let metadata = fs::symlink_metadata(entry.path()).map_err(io_error)?; + if metadata.file_type().is_symlink() { + return Err(error(2, "symlinked entries in run evidence are refused")); + } + if name == "receipt.json" && metadata.is_file() { + paths.push(entry.path()); + } else if name.starts_with("check-") && metadata.is_dir() { + let file = confined(&root, &format!("{name}/receipt.json"), false)?; + paths.push(file); + } + } + paths.sort(); + let mut receipts = Vec::new(); + for path in paths { + let receipt = ExecutionReceipt::parse(&read_bounded(&path, MAX_JSON)?).map_err(invalid)?; + for artifact in receipt_artifacts(&receipt) { + add_artifact(verified, &root, artifact)?; + } + receipts.push(receipt); + } + Ok(receipts) +} + +fn evaluate_options(options: EvaluateOptions) -> Result { + let source_root = root(&options.root)?; + let (_, plan) = read_plan(&options.plan)?; + let paths: Vec<_> = plan.subject.inputs.iter().map(|a| a.path.clone()).collect(); + let mut current = plan.subject.clone(); + current.revision = revision(&source_root)?; + current.inputs = inputs(&source_root, &paths, true)?; + // An absent selected file is stale evidence, not a synthetic empty subject. + if current.inputs.is_empty() { + return Err(error( + 1, + "all selected source inputs are missing; evidence is stale", + )); + } + current.dirty = selected_dirty(&source_root, &paths)?; + current.working_tree = if current.dirty { + Some(Artifact { + path: "current-selected-inputs.json".into(), + sha256: crate::sha256(&json_bytes(¤t.inputs)?), + }) + } else { + None + }; + if let Some(path) = &options.current_subject { + let (_, bytes) = read_explicit(path, MAX_JSON)?; + let supplied: Subject = crate::from_json(&bytes).map_err(invalid)?; + supplied.validate().map_err(invalid)?; + if supplied.repository != current.repository + || supplied.configuration != current.configuration + || supplied.revision != current.revision + || supplied.inputs != current.inputs + || supplied.dirty != current.dirty + { + return Err(error( + 2, + "supplied current subject contradicts the observed source snapshot", + )); + } + } + let mut verified = VerifiedArtifacts::default(); + let mut receipts = Vec::new(); + for directory in &options.receipts { + receipts.extend(load_receipts(directory, &mut verified)?); + } + let mut context_data = ContextFile::default(); + if let Some(path) = &options.context { + let (context_root, bytes) = read_explicit(path, MAX_JSON)?; + context_data = crate::from_json(&bytes).map_err(invalid)?; + for artifact in context_data + .audits + .iter() + .map(|a| &a.artifact) + .chain(context_data.manual_observations.iter().map(|m| &m.artifact)) + { + add_artifact(&mut verified, &context_root, artifact)?; + } + } + let mut ancestors = Vec::new(); + if current.revision != plan.subject.revision + && git( + &source_root, + &[ + "merge-base", + "--is-ancestor", + &plan.subject.revision, + ¤t.revision, + ], + )? + .status + .success() + { + ancestors.push(plan.subject.revision.clone()); + } + let mut context = + crate::EvaluationContext::new(options.as_of_ms.unwrap_or_else(now_ms), ¤t, &verified); + context.ancestor_revisions = &ancestors; + context.audits = &context_data.audits; + context.manual_observations = &context_data.manual_observations; + let mut aliases = BTreeSet::new(); + for declaration in context_data.families { + if !aliases.insert(declaration.route.clone()) { + return Err(error(2, "duplicate model-family declaration")); + } + context + .families + .declare( + &declaration.route, + sealmap_corpus::route::Family::named(&declaration.family).map_err(invalid)?, + ) + .map_err(invalid)?; + } + let report = crate::evaluate(&plan, &receipts, &context); + if options.json { + print_json(&report)?; + } else { + println!( + "{:?}: {}/{} required checks passed; {} expectation(s)", + report.outcome, + report.passed_required_checks, + report.required_checks, + report.expectations.len() + ); + for check in &report.checks { + println!( + "{}: {:?} — {}", + check.id, + check.outcome, + check.reasons.join("; ") + ); + } + for expectation in &report.expectations { + println!( + "{}: {:?} — {}", + expectation.id, + expectation.outcome, + expectation.reasons.join("; ") + ); + } + for error in &report.errors { + eprintln!("visioncraft: {error}"); + } + } + Ok(match report.outcome { + GateOutcome::Passed => 0, + GateOutcome::Blocked | GateOutcome::Incomplete => 1, + GateOutcome::Error => 70, + }) +} + +/// Dispatch an explicit CLI operation. Imported evidence is never executed. +/// +/// # Errors +/// Returns typed usage, filesystem or execution failures; raw source bytes are +/// retained privately rather than interpolated into diagnostics. +pub fn execute(cli: Cli, cancelled: &AtomicBool) -> Result { + match cli.command { + Operation::Plan { + command: PlanCommand::Init(options), + } => init(options), + Operation::Plan { + command: PlanCommand::Check { plan, json }, + } => { + let (_, plan) = read_plan(&plan)?; + if json { + print_json( + &serde_json::json!({"valid":true,"plan_sha256":plan.digest().map_err(invalid)?,"checks":plan.checks.len(),"expectations":plan.expectations.len(),"commands_executed":false}), + )?; + } else { + println!( + "Valid plan: {} checks, {} expectations; no check commands executed", + plan.checks.len(), + plan.expectations.len() + ); + } + Ok(0) + } + Operation::Run(options) => run(options, cancelled), + Operation::Evaluate(options) + | Operation::Gate { + command: GateCommand::Evaluate(options), + } + | Operation::Expectations { + command: ExpectationCommand::Check(options), + } => evaluate_options(options), + Operation::Deepsec(options) => { + crate::deepsec::execute(&options, cancelled).map_err(|e| error(e.code, e.message)) + } + } +} diff --git a/src/main.rs b/src/main.rs new file mode 100644 index 0000000..5ebd2cc --- /dev/null +++ b/src/main.rs @@ -0,0 +1,38 @@ +//! VisionCraft's explicit command-line entry point and cancellation bridge. +use clap::Parser; +use std::process::ExitCode; +use std::sync::{Arc, atomic::AtomicBool}; +use visioncraft::cli::Cli; + +fn main() -> ExitCode { + let cli = match Cli::try_parse() { + Ok(cli) => cli, + Err(error) => { + let failed = error.use_stderr(); + let _ = error.print(); + let legacy = std::env::args().nth(1).as_deref() == Some("deepsec"); + return ExitCode::from(if !failed { + 0 + } else if legacy { + 78 + } else { + 2 + }); + } + }; + let cancelled = Arc::new(AtomicBool::new(false)); + #[cfg(unix)] + for signal in [signal_hook::consts::SIGINT, signal_hook::consts::SIGTERM] { + if signal_hook::flag::register(signal, cancelled.clone()).is_err() { + eprintln!("visioncraft: could not install cancellation handler"); + return ExitCode::from(70); + } + } + match visioncraft::cli::execute(cli, &cancelled) { + Ok(code) => ExitCode::from(u8::try_from(code).unwrap_or(70)), + Err(error) => { + eprintln!("visioncraft: {}", error.message); + ExitCode::from(u8::try_from(error.code).unwrap_or(70)) + } + } +} diff --git a/tests/native_cli.rs b/tests/native_cli.rs new file mode 100644 index 0000000..622519c --- /dev/null +++ b/tests/native_cli.rs @@ -0,0 +1,406 @@ +//! Executed native CLI contracts using local temporary Git fixtures only. +#![cfg(all(unix, feature = "cli"))] + +use std::fs; +use std::path::Path; +use std::process::{Command, Output}; +use visioncraft::{ExecutionReceipt, QualityPlan}; + +fn git(root: &Path, args: &[&str]) -> Output { + let output = Command::new("git") + .args(["-c", "core.hooksPath=/dev/null", "-C"]) + .arg(root) + .args(args) + .output() + .unwrap(); + assert!( + output.status.success(), + "git {args:?}: {}", + String::from_utf8_lossy(&output.stderr) + ); + output +} + +fn fixture() -> tempfile::TempDir { + let root = tempfile::tempdir().unwrap(); + git(root.path(), &["init", "-q"]); + fs::write(root.path().join("source.txt"), "original\n").unwrap(); + git(root.path(), &["add", "source.txt"]); + git( + root.path(), + &[ + "-c", + "user.name=Fixture", + "-c", + "user.email=fixture@example.invalid", + "commit", + "-qm", + "baseline", + ], + ); + root +} + +fn cli(root: &Path, args: &[&str]) -> Output { + Command::new(env!("CARGO_BIN_EXE_visioncraft")) + .current_dir(root) + .args(args) + .output() + .unwrap() +} + +fn success(output: &Output) { + assert!( + output.status.success(), + "stdout={} stderr={}", + String::from_utf8_lossy(&output.stdout), + String::from_utf8_lossy(&output.stderr) + ); +} + +fn init(root: &Path, script: &str) { + success(&cli( + root, + &[ + "plan", + "init", + "--out", + "plan.json", + "--input", + "source.txt", + "--configuration", + "native fixture", + "--", + "/bin/sh", + "-c", + script, + ], + )); +} + +fn run(root: &Path) -> Output { + cli(root, &["run", "plan.json", "--all", "--out", "evidence"]) +} + +fn evaluate(root: &Path) -> Output { + cli( + root, + &["evaluate", "plan.json", "--receipts", "evidence", "--json"], + ) +} + +#[test] +fn plan_run_and_evaluate_use_real_output_but_do_not_invent_scope_or_tests() { + use std::os::unix::fs::PermissionsExt; + let root = fixture(); + init(root.path(), "printf 'real-output'; printf 'real-error' >&2"); + success(&cli(root.path(), &["plan", "check", "plan.json", "--json"])); + success(&run(root.path())); + let receipt = ExecutionReceipt::parse( + &fs::read(root.path().join("evidence/check-0000/receipt.json")).unwrap(), + ) + .unwrap(); + assert_eq!(receipt.observed_scope, None); + assert!(receipt.observed_tests.is_empty()); + assert_eq!( + fs::read(root.path().join("evidence/check-0000/stdout.log")).unwrap(), + b"real-output" + ); + assert_eq!( + fs::read(root.path().join("evidence/check-0000/stderr.log")).unwrap(), + b"real-error" + ); + let result = evaluate(root.path()); + success(&result); + let report: serde_json::Value = serde_json::from_slice(&result.stdout).unwrap(); + assert_eq!(report["outcome"], "passed"); + assert_eq!( + fs::metadata(root.path().join("evidence")) + .unwrap() + .permissions() + .mode() + & 0o777, + 0o700 + ); + assert_eq!( + fs::metadata(root.path().join("evidence/check-0000/stdout.log")) + .unwrap() + .permissions() + .mode() + & 0o777, + 0o600 + ); + git( + root.path(), + &["check-ignore", "evidence/check-0000/receipt.json"], + ); + success(&cli( + root.path(), + &[ + "expectations", + "check", + "plan.json", + "--receipts", + "evidence", + "--json", + ], + )); + success(&cli( + root.path(), + &[ + "gate", + "evaluate", + "plan.json", + "--receipts", + "evidence", + "--json", + ], + )); +} + +#[test] +fn failing_exit_retains_receipts_and_blocks_the_declared_gate() { + let root = fixture(); + init(root.path(), "printf 'assertion-reached' >&2; exit 9"); + assert_eq!(run(root.path()).status.code(), Some(1)); + let result = evaluate(root.path()); + assert_eq!(result.status.code(), Some(1)); + let report: serde_json::Value = serde_json::from_slice(&result.stdout).unwrap(); + assert_eq!(report["outcome"], "blocked"); + assert!( + root.path() + .join("evidence/check-0000/receipt.json") + .is_file() + ); +} + +#[test] +fn source_drift_before_execution_refuses_to_launch_and_after_execution_is_stale() { + let root = fixture(); + init(root.path(), "printf reached > SHOULD_NOT_RUN"); + fs::write(root.path().join("source.txt"), "changed\n").unwrap(); + assert_eq!(run(root.path()).status.code(), Some(1)); + assert!(!root.path().join("SHOULD_NOT_RUN").exists()); + assert!(!root.path().join("evidence").exists()); + fs::write(root.path().join("source.txt"), "original\n").unwrap(); + success(&run(root.path())); + fs::write(root.path().join("source.txt"), "changed again\n").unwrap(); + let result = evaluate(root.path()); + assert_eq!(result.status.code(), Some(1)); + assert_eq!( + serde_json::from_slice::(&result.stdout).unwrap()["outcome"], + "incomplete" + ); +} + +#[test] +fn deleting_selected_input_records_actual_empty_after_state() { + let root = fixture(); + init(root.path(), "rm source.txt"); + assert_eq!(run(root.path()).status.code(), Some(1)); + let receipt = ExecutionReceipt::parse( + &fs::read(root.path().join("evidence/check-0000/receipt.json")).unwrap(), + ) + .unwrap(); + assert!(receipt.inputs_after.is_empty()); + assert_eq!(evaluate(root.path()).status.code(), Some(1)); +} + +#[test] +fn evaluation_never_executes_a_command_recorded_in_an_imported_receipt() { + let root = fixture(); + init(root.path(), "printf valid"); + success(&run(root.path())); + let path = root.path().join("evidence/check-0000/receipt.json"); + let mut receipt: serde_json::Value = serde_json::from_slice(&fs::read(&path).unwrap()).unwrap(); + receipt["invocation"]["args"] = serde_json::json!(["-c", "touch RECEIPT_EXECUTED"]); + fs::write(&path, serde_json::to_vec_pretty(&receipt).unwrap()).unwrap(); + assert!(!evaluate(root.path()).status.success()); + assert!(!root.path().join("RECEIPT_EXECUTED").exists()); +} + +#[test] +fn altered_or_symlinked_evidence_cannot_borrow_an_existing_success() { + use std::os::unix::fs::symlink; + let root = fixture(); + init(root.path(), "printf expected"); + success(&run(root.path())); + let output = root.path().join("evidence/check-0000/stdout.log"); + fs::write(&output, "altered").unwrap(); + assert!(!evaluate(root.path()).status.success()); + let outside = tempfile::tempdir().unwrap(); + fs::write(outside.path().join("private"), "PRIVATE_SENTINEL").unwrap(); + fs::remove_file(&output).unwrap(); + symlink(outside.path().join("private"), &output).unwrap(); + let result = evaluate(root.path()); + assert!(!result.status.success()); + assert!(!String::from_utf8_lossy(&result.stderr).contains("PRIVATE_SENTINEL")); + assert!(!String::from_utf8_lossy(&result.stdout).contains("PRIVATE_SENTINEL")); +} + +#[test] +fn input_output_and_cwd_symlinks_are_refused_with_ordinary_root_alias_control() { + use std::os::unix::fs::symlink; + let root = fixture(); + let outside = tempfile::tempdir().unwrap(); + fs::write(outside.path().join("file"), "outside").unwrap(); + symlink(outside.path().join("file"), root.path().join("linked.txt")).unwrap(); + assert!( + !cli( + root.path(), + &[ + "plan", + "init", + "--out", + "bad.json", + "--input", + "linked.txt", + "--configuration", + "fixture", + "--", + "/bin/true" + ] + ) + .status + .success() + ); + assert!(!root.path().join("bad.json").exists()); + init(root.path(), "printf ok"); + symlink(outside.path(), root.path().join("redirect")).unwrap(); + assert!( + !cli( + root.path(), + &["run", "plan.json", "--all", "--out", "redirect/evidence"] + ) + .status + .success() + ); + assert!(!outside.path().join("evidence").exists()); + let alias_root = tempfile::tempdir().unwrap(); + symlink(root.path(), alias_root.path().join("source")).unwrap(); + success(&cli( + root.path(), + &[ + "run", + "plan.json", + "--root", + alias_root.path().join("source").to_str().unwrap(), + "--all", + "--out", + "evidence", + ], + )); +} + +#[test] +fn dirty_snapshots_are_exact_private_ignored_and_required_for_execution() { + let root = fixture(); + fs::write(root.path().join("source.txt"), "PRIVATE_DIRTY_SOURCE\n").unwrap(); + init(root.path(), "printf ok"); + let plan = QualityPlan::parse(&fs::read(root.path().join("plan.json")).unwrap()).unwrap(); + assert!(plan.subject.dirty); + let snapshot = plan.subject.working_tree.unwrap(); + let bytes = fs::read(root.path().join(&snapshot.path)).unwrap(); + assert_eq!(visioncraft::sha256(&bytes), snapshot.sha256); + git(root.path(), &["check-ignore", &snapshot.path]); + success(&run(root.path())); + success(&evaluate(root.path())); + fs::write(root.path().join(snapshot.path), "corrupted").unwrap(); + assert!( + !cli( + root.path(), + &["run", "plan.json", "--all", "--out", "another-attempt"] + ) + .status + .success() + ); + assert!(!root.path().join("another-attempt").exists()); +} + +#[test] +fn plan_and_evaluation_do_not_trigger_repository_clean_filters() { + let root = fixture(); + fs::write( + root.path().join(".gitattributes"), + "source.txt filter=canary\n", + ) + .unwrap(); + git(root.path(), &["add", ".gitattributes"]); + git( + root.path(), + &[ + "-c", + "user.name=Fixture", + "-c", + "user.email=fixture@example.invalid", + "commit", + "-qm", + "filter declaration", + ], + ); + git( + root.path(), + &[ + "config", + "filter.canary.clean", + "touch FILTER_EXECUTED; cat", + ], + ); + fs::write(root.path().join("source.txt"), "changed\n").unwrap(); + git( + root.path(), + &["hash-object", "--path=source.txt", "source.txt"], + ); // positive control: the configured filter is executable. + assert!(root.path().join("FILTER_EXECUTED").exists()); + fs::remove_file(root.path().join("FILTER_EXECUTED")).unwrap(); + init(root.path(), "printf ok"); + success(&run(root.path())); + success(&evaluate(root.path())); + assert!(!root.path().join("FILTER_EXECUTED").exists()); +} + +#[test] +fn fresh_directory_and_one_selection_are_required() { + let root = fixture(); + init(root.path(), "printf ok"); + success(&run(root.path())); + let before = fs::read(root.path().join("evidence/check-0000/receipt.json")).unwrap(); + assert!(!run(root.path()).status.success()); + assert_eq!( + fs::read(root.path().join("evidence/check-0000/receipt.json")).unwrap(), + before + ); + assert_eq!( + cli( + root.path(), + &[ + "run", + "plan.json", + "--all", + "--check", + "check", + "--out", + "unused" + ] + ) + .status + .code(), + Some(2) + ); + assert!(!root.path().join("unused").exists()); +} + +#[test] +fn signal_termination_still_preserves_a_valid_nonpassing_receipt() { + let root = fixture(); + init(root.path(), "kill -TERM $$"); + let result = run(root.path()); + assert_eq!(result.status.code(), Some(130)); + let receipt = ExecutionReceipt::parse( + &fs::read(root.path().join("evidence/check-0000/receipt.json")).unwrap(), + ) + .unwrap(); + assert_eq!(receipt.process, visioncraft::ProcessStatus::Interrupted); + assert!(receipt.signal.is_some()); + assert!(!evaluate(root.path()).status.success()); +} From 899e76600119a5159869551b374600d4cfb4a83e Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 3 Nov 2026 11:01:22 +0000 Subject: [PATCH 06/16] docs: integrate pinned Deepsec and direct AQE evidence workflows --- contracts/agentic-qe.json | 304 ++++++++++++++++++ contracts/deepsec.json | 110 +++++++ docs/PROVENANCE.md | 17 + docs/UPSTREAM-DEEPSEC.md | 105 ++++++ skills/visioncraft/SKILL.md | 1 + skills/visioncraft/assets/provenance.json | 27 +- skills/visioncraft/references/agentic-qe.md | 152 +++++++++ skills/visioncraft/references/architecture.md | 7 + skills/visioncraft/references/deepsec.md | 18 ++ .../references/ecosystem-agentbox.md | 15 + .../visioncraft/references/quality-gates.md | 7 + .../visioncraft/references/worked-examples.md | 5 + 12 files changed, 759 insertions(+), 9 deletions(-) create mode 100644 contracts/agentic-qe.json create mode 100644 contracts/deepsec.json create mode 100644 docs/UPSTREAM-DEEPSEC.md create mode 100644 skills/visioncraft/references/agentic-qe.md diff --git a/contracts/agentic-qe.json b/contracts/agentic-qe.json new file mode 100644 index 0000000..3a9ef31 --- /dev/null +++ b/contracts/agentic-qe.json @@ -0,0 +1,304 @@ +{ + "schema_version": 1, + "protocol_version": "agentic-qe-mcp-3.15.10-v1", + "supported_versions": [ + "3.15.10" + ], + "boundary": "Optional direct upstream MCP tools; no VisionCraft AQE executor and no forked agents. These JSON Schemas type a consumed result subset; they do not judge semantic truth or grant a policy pass.", + "package": { + "name": "agentic-qe", + "version": "3.15.10", + "repository": "https://github.com/proffesor-for-testing/agentic-qe", + "tarball_url": "https://registry.npmjs.org/agentic-qe/-/agentic-qe-3.15.10.tgz", + "integrity": "sha512-FNnyME/VHonPlRDB7Pu6Y62G0hizqAete466TgGU4UsFpfWfwPNr5seJW8x0HriaG9TZFPB5x6fRsoTyfCsANg==", + "shasum": "1509b5b961a6186887a83c6112592af1cbfc740a", + "licence": "MIT", + "npm_git_head": null, + "registry_provenance_git_commit": "e5814a2f4f3d7995b87ebda9ad30e8a3d92cd555", + "registry_provenance_url": "https://registry.npmjs.org/-/npm/v1/attestations/agentic-qe@3.15.10", + "source_identity_limit": "Registry SLSA statement decoded and tarball subject digest matched; attestation signature not independently verified in this check." + }, + "tools": { + "test_generate_enhanced": { + "input_fields": [ + "sourceCode", + "filePath", + "language", + "testType", + "framework", + "coverageGoal", + "behaviorExamples", + "aiEnhancement", + "detectAntiPatterns", + "saveResults" + ], + "required_input_fields": [], + "result_data_schema": "test_generation_data", + "meaning": "Candidate source; actual test execution remains required." + }, + "coverage_analyze_sublinear": { + "input_fields": [ + "target", + "detectGaps", + "saveResults" + ], + "required_input_fields": [ + "target" + ], + "result_data_schema": "coverage_data", + "meaning": "Measured, estimated and unmeasured are distinct; native report/source evidence required." + }, + "quality_assess": { + "input_fields": [ + "runGate", + "metrics", + "target", + "sourceFiles", + "saveResults" + ], + "required_input_fields": [], + "result_data_schema": "quality_data", + "meaning": "Analysis is not gate execution; insufficient evidence cannot pass." + } + }, + "output_schemas": { + "test_generation_data": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "required": [ + "status", + "tests", + "llmEnhanced" + ], + "properties": { + "status": { + "const": "completed" + }, + "tests": { + "type": "array", + "items": { + "type": "object", + "properties": { + "testCode": { + "type": "string" + }, + "generationMode": { + "type": "string" + } + }, + "additionalProperties": true + } + }, + "llmEnhanced": { + "type": "boolean" + }, + "generationMode": { + "type": "string" + }, + "coverageEstimate": { + "type": [ + "number", + "null" + ] + } + }, + "additionalProperties": true + }, + "coverage_data": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "required": [ + "status", + "measured", + "estimated", + "coverageMethod", + "lineCoverage", + "branchCoverage", + "functionCoverage", + "branchDataCollected", + "functionDataCollected" + ], + "properties": { + "status": { + "const": "completed" + }, + "measured": { + "type": "boolean" + }, + "estimated": { + "type": "boolean" + }, + "coverageMethod": { + "type": "string" + }, + "lineCoverage": { + "type": [ + "number", + "null" + ] + }, + "branchCoverage": { + "type": [ + "number", + "null" + ] + }, + "functionCoverage": { + "type": [ + "number", + "null" + ] + }, + "branchDataCollected": { + "type": "boolean" + }, + "functionDataCollected": { + "type": "boolean" + }, + "unmeasured": { + "type": "boolean" + }, + "runStatus": { + "enum": [ + "passed", + "failed" + ] + } + }, + "additionalProperties": true + }, + "quality_data": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "required": [ + "passed", + "gateEvaluated" + ], + "properties": { + "passed": { + "type": "boolean" + }, + "gateEvaluated": { + "type": "boolean" + }, + "status": { + "type": "string" + }, + "evidenceStatus": { + "type": "string" + }, + "unmeasured": { + "type": "array", + "items": { + "type": "string" + } + }, + "checks": { + "type": "array", + "items": { + "type": "object" + } + }, + "measuredFailures": { + "type": "array", + "items": { + "type": "object" + } + } + }, + "additionalProperties": true + } + }, + "raw_response_policy": { + "retain_complete_mcp_envelope": true, + "retain_handler_envelope": true, + "reject_for_pass": [ + "isError true", + "success false", + "non-JSON or truncated text", + "unknown result shape", + "missing required capability", + "insufficient-evidence", + "stale or mismatched source/report" + ], + "missing_fields": "Unknown/incomplete; never fill with successful defaults. A loop-steering text prefix or compacted response needs retained original evidence, not heuristic green parsing." + }, + "evidence_fields": [ + "tool_server_identity", + "tool_name", + "tool_schema_digest", + "aqe_version", + "aqe_package_integrity", + "protocol_version", + "request", + "raw_response_path", + "raw_response_sha256", + "source_revision", + "source_dirty_inputs", + "started_at", + "completed_at", + "native_test_command", + "native_test_output_sha256" + ], + "memory": { + "supported_env": { + "AQE_MEMORY_BACKEND": "memory", + "AQE_WORKERS_ENABLED": "false" + }, + "memory_mode_disables_embedding_attempts": false, + "embedding_endpoint": "OpenAI-style POST /v1/embeddings; bearer token via AQE_EMBEDDER_TOKEN", + "default_model": "Xenova/all-MiniLM-L6-v2", + "dimensions": 384, + "durable_owner": "Host-approved memory API; no raw SQL or automatic second service." + }, + "verification": { + "tarball_integrity_verified": true, + "real_mcp_task_executed_by_this_inspection": false, + "sources": [ + { + "path": "dist/mcp/protocol-server.js", + "sha256": "04efa14b0204e5a1d6e8d3cf028beb63d7613a3a8be3d627b01bf84fb264b61c" + }, + { + "path": "dist/mcp/handlers/domain-handler-configs.js", + "sha256": "973683d0f2ea703e1c52f5d13ba02c126ca403f7652ee2a98495b8b9f765b706" + }, + { + "path": "dist/mcp/handlers/handler-factory.js", + "sha256": "e2fcbbed10e0e0582c24799f7ac1d49825ffe42d176868fa73962dad810771fa" + }, + { + "path": "dist/mcp/entry.js", + "sha256": "45c03af0a535e3302bced5e1e899f45ec5ca595c9bf1e8b106c80991c611bafd" + }, + { + "path": "dist/mcp/tools/base.js", + "sha256": "5ac126dffba550518918638841d4cc9bd57b9194407374d794708119605e3895" + }, + { + "path": "dist/mcp/services/session-store.js", + "sha256": "523d4fc8fdbf29941f567597a5298d40aad622f67aed43151600620b6b5298ef" + }, + { + "path": "dist/kernel/unified-memory.js", + "sha256": "9a215da71f71bda34c5241152fbc79fd4beeb29177e2c8fca792f0b756357051" + }, + { + "path": "dist/learning/experience-capture-middleware.js", + "sha256": "49d9feb583ead83e1d98056556806903a03dee38faaed1a88d3736f67661538a" + }, + { + "path": "dist/learning/real-embeddings.js", + "sha256": "9e34d325924f05256416340ddecb05e153a568291d9e349a33b52a793c4f5654" + }, + { + "path": "dist/learning/embedder-endpoint-client.js", + "sha256": "73bbd7036caaa7421cebb67d397f2f3d026dc452f7c5999685056db067216c55" + }, + { + "path": "dist/cli/commands/quality.js", + "sha256": "2bb07043fa6c49a1638bbbdeddc34da0c17e6262cde9b447232c4474d2a3f7c6" + } + ] + } +} diff --git a/contracts/deepsec.json b/contracts/deepsec.json new file mode 100644 index 0000000..2358485 --- /dev/null +++ b/contracts/deepsec.json @@ -0,0 +1,110 @@ +{ + "schema_version": 1, + "adapter_protocol_version": "deepsec-cli-2.3.10-v1", + "supported_versions": [ + "2.3.10" + ], + "unsupported_version": { + "outcome": "unavailable", + "exit_code": 78, + "may_satisfy_required_gate": false + }, + "package": { + "name": "deepsec", + "version": "2.3.10", + "registry_url": "https://registry.npmjs.org/deepsec/2.3.10", + "tarball_url": "https://registry.npmjs.org/deepsec/-/deepsec-2.3.10.tgz", + "integrity": "sha512-JybqShqRHJWdgqQKV6xwtf3p+QMW7wlmgoBtT1QISfns5A5JCO5r9E8b4mXgu7HEoY5HK+izdxI4con+ROLWdA==", + "shasum": "7213cb0e1abf54a4855efe0518d5d1b519b73f33", + "git_head": "ce646748b6b2d7b088107ac29944c4129c49f11d", + "licence": "Apache-2.0" + }, + "upstream": { + "repository": "https://github.com/vercel-labs/deepsec", + "release_source_url": "https://github.com/vercel-labs/deepsec/tree/ce646748b6b2d7b088107ac29944c4129c49f11d", + "package_manifest_url": "https://github.com/vercel-labs/deepsec/blob/ce646748b6b2d7b088107ac29944c4129c49f11d/packages/deepsec/package.json" + }, + "required_receipt_fields": [ + "deepsec_version", + "deepsec_git_head", + "deepsec_npm_integrity", + "deepsec_protocol_version" + ], + "receipt_field_semantics": { + "deepsec_version": "Version observed from the invoked CLI.", + "deepsec_git_head": "Expected npm release gitHead; not an independently observed installed-source revision.", + "deepsec_npm_integrity": "Expected npm tarball integrity; host installation evidence must establish that installed bytes came from this artifact.", + "deepsec_protocol_version": "Version of the VisionCraft protocol fixture contract applied to this invocation." + }, + "installed_documentation": [ + "SKILL.md", + "dist/docs/reviewing-changes.md", + "dist/docs/configuration.md", + "dist/docs/models.md", + "dist/docs/data-layout.md" + ], + "boundary": { + "optional": true, + "core_requires_deepsec": false, + "implementation": "External CLI adapter; no upstream reviewer fork.", + "host_owns": [ + "installation", + "dependency lock", + "credentials", + "model and route selection", + "source-sharing policy", + "spend authorisation", + "deployment activation" + ], + "visioncraft_owns": [ + "supported version check", + "explicit bounded invocation", + "private evidence capture", + "fresh completion and valid export checks", + "declared severity threshold" + ], + "never_implicit": [ + "init", + "login", + "installation", + "changing default model routes", + "paid review", + "activation" + ] + }, + "verification": { + "checked_at": "2026-11-03T10:47:51Z", + "npm_tarball_integrity_verified": true, + "upstream_main_observed": "4fa67220aff67ac93dfc840206d3d32bfa4411ec", + "upstream_main_is_release_source": false, + "scope": "Registry metadata, downloaded tarball, bundled documentation and immutable upstream commit; no model review executed by this provenance check." + }, + "completion_protocol": { + "source_selection": "Nonempty explicit snapshot; direct processing uses --files-from and --no-ignore; staged/working mismatch refused; full processes selected pending scan candidates.", + "run_fields": [ + "type=process", + "runId", + "projectId", + "rootPath", + "phase=done", + "completedAt", + "stats.filesProcessed=expected_count" + ], + "file_fields": [ + "filePath", + "projectId", + "fileHash=expected_sha256", + "status=analyzed", + "analysisHistory exactly one current runId" + ], + "analysis_fields": [ + "refusal.refused=false", + "no skipped scope", + "usage.outputTokens>0", + "nonempty model", + "nonempty agentType" + ], + "empty_full_pending_set": "unavailable, no new review", + "semantic_boundary": "Recorded per-file investigations of exact selected bytes; dependencies/runtime behaviour remain separate." + } +} diff --git a/docs/PROVENANCE.md b/docs/PROVENANCE.md index 8b06de7..3ae6de8 100644 --- a/docs/PROVENANCE.md +++ b/docs/PROVENANCE.md @@ -68,6 +68,23 @@ Retained Rust digests carry their own underlying-source acknowledgements. Do not remove those notices or treat future upstream additions as covered by this import record without checking them. +## Optional upstream tool contracts + +Deepsec and Agentic QE are external installations, not vendored engines. +Their new operating guidance and protocol manifests are independently written +under the project licence. [Deepsec maintenance](UPSTREAM-DEEPSEC.md) and +`contracts/deepsec.json` identify the inspected npm 2.3.10 release, immutable +source commit and verified tarball integrity. + +`contracts/agentic-qe.json` identifies npm 3.15.10 and hashes the inspected +published MCP/CLI implementation files. The npm metadata did not expose a +`gitHead`; its registry SLSA statement reports +`e5814a2f4f3d7995b87ebda9ad30e8a3d92cd555` at tag `v3.15.10`. The tarball SHA-512 +matched both npm integrity and the decoded attestation's subject. This check +did not independently verify the attestation signature. Typed schemas describe +the result subset VisionCraft's guidance consumes; they are not an implementation +of AQE or a claim that a real MCP task was run during source inspection. + ## Evidence limits Structural checks, licence manifests and path coverage do not establish a diff --git a/docs/UPSTREAM-DEEPSEC.md b/docs/UPSTREAM-DEEPSEC.md new file mode 100644 index 0000000..c50fe29 --- /dev/null +++ b/docs/UPSTREAM-DEEPSEC.md @@ -0,0 +1,105 @@ +# Maintaining the optional Deepsec adapter + +VisionCraft adapts the external [Deepsec CLI](https://github.com/vercel-labs/deepsec). +It does not fork Deepsec's reviewer agents, implement their reasoning, or require +Deepsec for its core planning and evidence functions. A host installs the tool, +chooses credentials and model routes, authorises source access and spend, and +decides when to activate an update. VisionCraft checks a supported protocol, +bounds an explicit invocation, retains evidence and applies a declared threshold. + +## Current protocol pin + +[contracts/deepsec.json](../contracts/deepsec.json) is the machine-readable release +identity and adapter protocol declaration. The inspected npm release is +`deepsec@2.3.10`, with npm `gitHead` +`ce646748b6b2d7b088107ac29944c4129c49f11d`. Its +[immutable package manifest](https://github.com/vercel-labs/deepsec/blob/ce646748b6b2d7b088107ac29944c4129c49f11d/packages/deepsec/package.json) +declares that version and Apache-2.0 licensing. The registry tarball's SHA-512 +integrity was independently recomputed and matched the registry metadata. + +These read-only commands retrieve the release facts without installing it or +running lifecycle scripts: + +```sh +npm view deepsec@2.3.10 version dist gitHead repository --json +npm pack deepsec@2.3.10 --ignore-scripts --json --pack-destination ./evidence +``` + +Create the evidence directory first. Inspect the downloaded package's `SKILL.md` +and `dist/docs/{reviewing-changes,configuration,models,data-layout}.md`; they +describe the installed release, whereas upstream `main` can describe newer code. +At the 2026-11-03 check, upstream `main` was +`4fa67220aff67ac93dfc840206d3d32bfa4411ec`, a different commit from npm 2.3.10. +A moving tag or a current README does not update this protocol pin. + +Receipts must retain the observed CLI version, expected npm git commit, expected +npm integrity and VisionCraft protocol-fixture version. The expected commit and +integrity identify the approved release; they do not prove which bytes are in +an installed binary. Host installation/lock evidence establishes that additional +fact. Unsupported versions are unavailable (exit 78), never an implicit pass. + +## Completion and scope contract + +VisionCraft freezes a nonempty selected file set and its hashes. Direct processing +uses that explicit set with Deepsec's `--files-from` and `--no-ignore`, avoiding +a second independently computed diff. A staged selection whose working bytes +differ is refused; use an exact index checkout. Full mode scans first, then +processes the selected pending candidates. No pending candidates means no new +review, not a clean full review. Scan-only output cannot satisfy model review. + +Completion requires one fresh persisted processing run for the expected project +and root, phase `done`, a completion timestamp, and a processed-file count equal +to the selected review set. Every selected file must have an `analyzed` record +with the expected path, project and content hash, plus exactly one history entry +for that run. That entry must name the model and agent, report positive output +tokens, state `refusal.refused: false`, and contain no skipped scope. Missing, +zero-work, refused, partial or contradictory records prevent a pass. + +Retain the run and file records, raw export, normalised findings and all bounded +process output. Exit 1 alone does not distinguish findings from runtime failure; +the pinned completion path and valid export remain necessary. A comment alone +does not prove that every intended file was reviewed. Aggregate exports can +contain historical findings: retain them and distinguish the current attempt. +These protocol checks verify recorded investigations of selected bytes. They +cannot prove semantic correctness, dependency coverage or runtime safety. + +## Update checklist + +1. Fetch exact npm metadata and integrity, identify its immutable upstream + source, and inspect its bundled help/docs. Do not substitute upstream `main`. + Verify licences and changes to transitive reviewer/tool dependencies. +2. Diff source-selection flags, project/root resolution, model/auth routes, + configuration precedence, cache/resume rules, run/file records, export + schema, severity vocabulary and exit behaviour. Record deliberate changes + to the adapter protocol version. +3. Run compatibility fixtures for a clean completed review and a completed + finding, alongside missing inputs, empty selection, stale state, malformed + export, unknown severity, source mutation, wrong project/hash, zero output, + refusal/partial scope, provider failure, timeout and cancellation. Include + output bounds, managed-path checks and cleanup of child processes. +4. Perform one bounded real smoke review under explicit host authority using + non-sensitive fixture source and approved credentials. Record the actual + model, current run/file records, export, cost when available and limitations. + Local fixture success does not establish a real provider's completion path. +5. Update the contract, fixture version, adapter and docs together. Align the + exact host package pin, lock/integrity and consumer tests; do not loosen the + version check just to accept a newer executable. +6. Release the tested change, update consumer pins, rebuild through the host's + normal delivery process, then observe the installed version and a bounded + activation check. Preserve source, publication, adoption and deployment + evidence separately. + +An optional release monitor should only open a reviewable update PR containing +the proposed pin, source comparison and compatibility work. This is a proposed +maintenance workflow, not an installed monitor. It must not auto-activate the +release, change default models, initialise accounts or start paid reviews. + +## Host responsibilities + +VisionCraft never implicitly installs Deepsec, runs `init` or login, changes +global defaults, or chooses a new credential provider. It does not create a +sandbox: the invoked reviewer and its children have the authority granted by +the host. Source-bearing output stays in private evidence locations according +to that host's policy. See the portable +[operating method](../skills/visioncraft/references/deepsec.md) and +[Agentbox example](../skills/visioncraft/references/ecosystem-agentbox.md). diff --git a/skills/visioncraft/SKILL.md b/skills/visioncraft/SKILL.md index 3a0146b..821535a 100644 --- a/skills/visioncraft/SKILL.md +++ b/skills/visioncraft/SKILL.md @@ -32,6 +32,7 @@ command surface. | Specifications, prompts and delivery need lineage | [Traceability](references/traceability.md) | | An audit or reviewer supplied findings | [Review evidence](references/review-evidence.md) | | A merge/release needs applicable checks | [Quality gates](references/quality-gates.md), [Deepsec adapter](references/deepsec.md) | +| Candidate tests, coverage gaps or measured quality tools would help | [Optional Agentic QE](references/agentic-qe.md) | | Rust is being written, reviewed or ported | [Steering](references/rust/steering.md), [review](references/rust/review.md), [port](references/rust/port.md) | | Several participants are actually available | [Logical roles](references/roles.md) | | A concrete project example helps scope the work | [Five worked examples](references/worked-examples.md) | diff --git a/skills/visioncraft/assets/provenance.json b/skills/visioncraft/assets/provenance.json index e3b1298..9d869d2 100644 --- a/skills/visioncraft/assets/provenance.json +++ b/skills/visioncraft/assets/provenance.json @@ -40,6 +40,12 @@ "treatment": "newly written guidance or migration data from the behavioural inventory", "behavioural_sources": [] }, + { + "path": "assets/provenance.json", + "licence": "MIT OR Apache-2.0", + "treatment": "newly written file-level provenance manifest", + "behavioural_sources": [] + }, { "path": "assets/traceability.md", "licence": "MIT OR Apache-2.0", @@ -52,6 +58,17 @@ "treatment": "newly written guidance or migration data from the behavioural inventory", "behavioural_sources": [] }, + { + "path": "references/agentic-qe.md", + "licence": "MIT OR Apache-2.0", + "treatment": "New guidance from read-only inspection of published agentic-qe 3.15.10 MCP/CLI contracts; no upstream implementation copied.", + "behavioural_sources": [], + "external_source": { + "package": "agentic-qe", + "version": "3.15.10", + "contract": "contracts/agentic-qe.json" + } + }, { "path": "references/architecture.md", "licence": "MIT OR Apache-2.0", @@ -153,9 +170,7 @@ "upstream": { "repository": "https://github.com/morganlinton/BeautifulRust", "revision": "a9cdcfa94d1330c0d41c7f67764c5f7786fbb71d", - "paths": [ - "LICENSE" - ] + "mapping_note": "Inherited full notice and attribution; source_import gives the verified imported file. No independently checked upstream licence-file path is asserted." }, "source_import": { "repository": "https://github.com/DreamLab-AI/agentbox", @@ -389,12 +404,6 @@ "behavioural_sources": [ "USAGE-EXAMPLES.md" ] - }, - { - "path": "assets/provenance.json", - "licence": "MIT OR Apache-2.0", - "treatment": "newly written file-level provenance manifest", - "behavioural_sources": [] } ], "limitations": [ diff --git a/skills/visioncraft/references/agentic-qe.md b/skills/visioncraft/references/agentic-qe.md new file mode 100644 index 0000000..c6d21e2 --- /dev/null +++ b/skills/visioncraft/references/agentic-qe.md @@ -0,0 +1,152 @@ +# Optional testing tools from Agentic QE + +[Agentic QE](https://github.com/proffesor-for-testing/agentic-qe) is a separate +upstream quality-engineering package. VisionCraft can use its direct MCP tools +for candidate tests, coverage gaps and quality observations. It does not copy +AQE's agents, turn role names into executed workers, or require AQE to develop +and test an ordinary project. Missing AQE leaves native tests and source review +available; a specifically required AQE observation remains unavailable. + +This reference inspects the npm `agentic-qe@3.15.10` package. Discover the actual +host MCP tool names and input schemas before calling them. A configured server +name, a coordination record or a newer upstream README is not proof that a tool +is callable. Do not invent a `visioncraft aqe` command. The host owns installation, +the pinned dependency closure, model/provider policy and external effects. + +## Direct tools and the useful boundary + +| Need | Upstream tool name and input | Evidence to retain | +|---|---|---| +| Candidate tests | `test_generate_enhanced`: `sourceCode`, `filePath`, explicit `language`, `framework`, `testType`, optional trusted `behaviorExamples`, `aiEnhancement`, `saveResults` | Generated source, `generationMode`/limits, `llmEnhanced`, actual subsequent test execution | +| Coverage gaps | `coverage_analyze_sublinear`: required `target`, `detectGaps`, `saveResults` | `measured`, `estimated`, `coverageMethod`, nullable metrics, collected-metric flags, source/report identity and gaps | +| Scoped static metrics | `quality_assess`: `runGate:false`, `target` or `sourceFiles`, `metrics`, `saveResults` | Requested and unmeasured metrics, exclusions, parse limits, measured failures; `gateEvaluated:false` remains analysis | +| AQE's measured gate | `quality_assess`: `runGate:true`, `saveResults` | Its canonical measured checks, freshness, `gateEvaluated`, `passed`, insufficient-evidence details | + +Names above are upstream names; a host may prefix them during MCP registration. +Use only parameters in the discovered schema. For example, internal handler +options are not automatically public MCP arguments. Native test tools remain +the authority for whether generated code compiles and its assertions pass. + +AQE's test-generation response can contain scaffolding and predicted coverage. +Neither is executed coverage. Trusted `behaviorExamples` in this release apply +to named JS/TS functions with simple required parameters and unit tests using +Vitest, Jest or node-test; do not imply that contract covers Rust or every test +framework. Other supported languages still need their real compiler and runner. +Inspect `generationMode`, each returned test body and limitations rather than +assuming that `testsGenerated` or a learning status proves useful tests exist. + +Coverage results can be measured, estimated or unmeasured. Keep nulls as nulls. +Require an explicit measurement claim and matching raw instrumentation before +using a percentage in a gate. The tool's name includes “sublinear”; VisionCraft +makes no complexity, speed or gap-detection accuracy claim from that name. + +`quality_assess` defaults to analysis. Its `runGate:true` branch requires all +seven canonical measurements in AQE's evidence contract, valid within 24 hours; +missing, malformed or stale measurements produce `insufficient-evidence`. +That fixed upstream policy does not replace a project's declared check set. +The CLI `aqe quality --format json` also evaluates that store, with exits 0 +(pass), 1 (failure), 2 (pass near a minimum threshold) and 3 (insufficient +evidence). Errors can also exit 1. In-memory state in one process is not an +evidence store shared with a later CLI process. + +## Worked source-to-test flow + +This is an invocation example, not an executed success report. In an owned +worktree, first record the source revision, relevant dirty bytes and intended +behaviour. For a named JS function, pass a trusted expectation that does not +derive its answer from the implementation: + +```json +{ + "sourceCode": "export function add(a, b) { return a + b; }", + "filePath": "src/add.js", + "language": "javascript", + "framework": "vitest", + "testType": "unit", + "behaviorExamples": [ + {"functionName": "add", "args": [2, 3], "expected": 5}, + {"functionName": "add", "args": [-2, 2], "expected": 0} + ], + "aiEnhancement": false, + "saveResults": false +} +``` + +Call the discovered `test_generate_enhanced` tool with that object. Preserve the +entire original MCP response, including `isError`, content blocks and the JSON +handler envelope. A steering message, truncated response or unrecognised shape +must not be silently converted into an empty success. Discovered schemas are +versioned observations; the package contract file records the consumed subset. + +Read the returned `testCode`, check imports and assertions, then deliberately +write appropriate tests into the worktree. Execute the project's real test +command. For an existing Vitest project whose test script supports it, this may +be `npm test -- --run`; inspect that project's scripts first. Retain its exit, +test count and output. Confirm a controlled wrong implementation fails the +intended assertion, restore the candidate, and rerun the valid control. Generated +text or a successful MCP call does not replace these steps. + +Run the project's existing instrumentation and retain its actual coverage report. +Then ask the discovered coverage tool to explain that scope: + +```json +{"target":"src/add.js","detectGaps":true,"saveResults":false} +``` + +Compare the tool's measurement/provenance fields against the native report and +current source. Treat static estimates as suggestions for the next test. Finish +with project-specific quality checks. If AQE's measured gate is also required, +call it explicitly and keep its incomplete result visible: + +```json +{"runGate":true,"saveResults":false} +``` + +Do not fill AQE's missing metrics with invented values or copy another run's +result to make this gate green. A maintainer can instead declare that upstream +gate inapplicable and use the project's meaningful checks, with that policy +choice visible before reporting readiness. + +## Process state, embeddings and durable lessons + +In 3.15.10, `AQE_MEMORY_BACKEND=memory` selects in-memory kernel storage and an +ephemeral SQLite store for internal subsystems; session/result persistence is +also gated. It does **not** turn off learning or all embedding attempts. +Experience capture still calls the embedding code. The optional external +endpoint uses OpenAI-style `/v1/embeddings`; otherwise it tries an optional local +transformer package. Do not install that package or start another embedding +service as a side effect of using the skill. + +AQE defaults to `Xenova/all-MiniLM-L6-v2`, with 384 +dimensions. Matching dimensions alone do not make it interchangeable with +another model. Reusing a host endpoint requires a supported model-selection +contract and verified identity, not merely the same vector length. If no valid +runtime exists, describe semantic learning as unavailable. Ordinary successful +test execution does not require a claim that semantic learning worked. + +Hosts may set the supported `AQE_WORKERS_ENABLED=false` for task-directed use; +this stops background worker/quality daemons, not every internal learning hook. +Use `saveResults:false` when the host retains the raw response itself. Verify +filesystem effects on a harmless fixture; an environment setting is not proof +that no path was written. No `aqe init`, template dump, model install or global +configuration mutation is required by this workflow. + +Retain reusable verified lessons through the host's existing approved memory +interface. In [Agentbox](ecosystem-agentbox.md), that is RuVector through its MCP +embedding pipeline; direct SQL, AQE's memory CLI and a second vector store are +not alternatives. AQE's temporary state can support a task without becoming the +estate's durable source of truth. + +## AQE and Ruflo are separate surfaces + +Ruflo can coordinate work in a host that provides it. That does not establish +that a direct AQE MCP domain tool ran. Record the actual executor/tool identity, +request, response, source and native test evidence. Prefer a direct discovered +domain tool for one concrete testing task; introduce orchestration only when +the task needs real available participants and the host authorises it. + +On upgrades, compare the pinned package schemas, handlers, memory/embedding +behaviour and actual fixture results. Include unsupported version, tool missing, +malformed output, error envelope, estimated coverage, stale cached data and +insufficient evidence controls. Keep upstream source and npm release distinct; +never relax result interpretation to disguise an unavailable capability. diff --git a/skills/visioncraft/references/architecture.md b/skills/visioncraft/references/architecture.md index f2bdd53..73a0b0a 100644 --- a/skills/visioncraft/references/architecture.md +++ b/skills/visioncraft/references/architecture.md @@ -38,6 +38,13 @@ redirection; they are not a general sandbox against hostile concurrent mutation. ## Optional knowledge services +[Agentic QE](agentic-qe.md) is an optional external testing engine. Its direct +MCP tools can generate candidate tests, analyse coverage or report quality +evidence. VisionCraft does not implement a second AQE executor or copy its +agents. Discover the host's actual tools and preserve their raw results; run +generated tests with the project's real toolchain before treating them as +evidence. Ruflo coordination and direct AQE execution are separate observations. + A project may retain episodic attempts and durable lessons, use exact tags for lookup, link entities/decisions, or combine lexical and semantic retrieval. Those are useful host capabilities when implemented. Do not assume a vector diff --git a/skills/visioncraft/references/deepsec.md b/skills/visioncraft/references/deepsec.md index c925d96..f42af01 100644 --- a/skills/visioncraft/references/deepsec.md +++ b/skills/visioncraft/references/deepsec.md @@ -10,6 +10,15 @@ Compatibility is based on the inspected Deepsec 2.3.10 protocol. Consult the installed version's own help/documentation before changing its flags or result interpretation. A later version needs compatibility evidence. +Deepsec remains an optional upstream dependency, maintained by its own project. +VisionCraft does not fork its reviewers. The package's `contracts/deepsec.json` +pins npm version, upstream commit, integrity and protocol-fixture version; the +package's `docs/UPSTREAM-DEEPSEC.md` gives the update procedure. Read bundled +release documentation, compare flags/configuration/exports/exits/model routes, +run completion and failure fixtures, perform an authorised bounded real smoke, +then align exact host pins before release and rebuild. A release monitor may +propose a PR; it must not auto-activate or start paid work. + ## Declare the attempt Choose exactly one supported scope/mode, the base revision or file list, @@ -38,6 +47,15 @@ threshold explicit, including bug categories such as `HIGH_BUG` and `BUG`. A policy pass means no counted finding crossed that threshold, not zero findings or a secure system. +VisionCraft also requires persisted completion evidence for the frozen file +set: one fresh completed processing run, matching project/root and processed +count, exact path/hash `analyzed` file records, and current-run history with +model/agent identity, positive output tokens, explicit non-refusal and no +skipped scope. A fresh comment alone is insufficient. Direct mode processes the +explicit files with `--no-ignore`; staged/working byte mismatches are refused. +Full mode processes scanned pending candidates; an empty set is unavailable, +not a successful full review. Retain those raw records alongside the export. + Legacy outcome conventions are 0 for completed policy pass (or separately labelled scan-only completion), 1 for blocking findings, 70 for runtime/export error, 78 for disabled/unavailable/configuration refusal, and 124 for deadline. diff --git a/skills/visioncraft/references/ecosystem-agentbox.md b/skills/visioncraft/references/ecosystem-agentbox.md index 27e210c..0b6d067 100644 --- a/skills/visioncraft/references/ecosystem-agentbox.md +++ b/skills/visioncraft/references/ecosystem-agentbox.md @@ -34,6 +34,21 @@ available workers and retain their execution provenance. Host-configured model defaults and advisors belong to that host. A same-family advisor is not an independent auditor, regardless of provider spelling or role label. +## Direct AQE testing tools + +Agentbox can enable its separately pinned `agentic-qe` toolchain and project a +direct `aqe mcp` server to its coding clients. Discovery must confirm callable +tools after the rebuild; an enabled source flag is not deployed evidence. +See [the AQE workflow](agentic-qe.md) for exact 3.15.10 input examples and result +limits. Jev selects VisionCraft's engineering method; AQE provides optional +domain execution, while Ruflo remains a separate coordination surface. + +Use the host's in-memory AQE setting and existing RuVector MCP for durable +lessons. Memory mode does not disable internal embedding attempts. Do not add a +new model service or assume that AQE's default model can be replaced by any +384-dimensional endpoint. Preserve unavailable learning capability separately +from working native tests, and verify actual filesystem/runtime behaviour. + ## Security adapter and review cadence Agentbox supplies toolchain pins, `[security.deepsec]` policy, route/credential diff --git a/skills/visioncraft/references/quality-gates.md b/skills/visioncraft/references/quality-gates.md index bbe8b24..85b41a3 100644 --- a/skills/visioncraft/references/quality-gates.md +++ b/skills/visioncraft/references/quality-gates.md @@ -45,6 +45,13 @@ subject revision and configuration. Paid external review follows the current project's cadence; do not run it automatically after every increment. A check before later edits must not be presented as review of the final diff. +When available, [AQE's direct tools](agentic-qe.md) can propose tests and explain +coverage gaps. Preserve the generated source and measurement provenance, then +run the real project tests and instrumentation. Its static analysis and fixed +seven-metric gate have different contracts; unavailable measurements must not +satisfy the project's required checks. Keep the complete raw MCP response +beside subsequent native test evidence. + ## Outcome dimensions Record process completion separately from evaluator judgement. A process can diff --git a/skills/visioncraft/references/worked-examples.md b/skills/visioncraft/references/worked-examples.md index 2d07af7..db41a28 100644 --- a/skills/visioncraft/references/worked-examples.md +++ b/skills/visioncraft/references/worked-examples.md @@ -5,6 +5,11 @@ versions and limits from the actual project. Expected behaviours below define example contracts; they do not claim test output, production readiness or a universal percentage gate. +An optional [AQE example](agentic-qe.md#worked-source-to-test-flow) shows candidate +generation, native test execution and measured coverage as separate steps. +Apply it where those tools are actually available; these five project examples +do not require an AQE installation or an orchestration service. + ## 1. A personal todo application **Request.** Add creation, editing, completion, deletion, filtering and local From 9da0c7a4c13b9ced159af1c3f167f99a743de1ab Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 3 Nov 2026 11:09:13 +0000 Subject: [PATCH 07/16] docs: mark pinned AQE model as an upstream lint exception --- skills/visioncraft/references/agentic-qe.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/visioncraft/references/agentic-qe.md b/skills/visioncraft/references/agentic-qe.md index c6d21e2..962bf85 100644 --- a/skills/visioncraft/references/agentic-qe.md +++ b/skills/visioncraft/references/agentic-qe.md @@ -117,7 +117,7 @@ endpoint uses OpenAI-style `/v1/embeddings`; otherwise it tries an optional loca transformer package. Do not install that package or start another embedding service as a side effect of using the skill. -AQE defaults to `Xenova/all-MiniLM-L6-v2`, with 384 +AQE defaults to `Xenova/all-MiniLM-L6-v2`, with 384 dimensions. Matching dimensions alone do not make it interchangeable with another model. Reusing a host endpoint requires a supported model-selection contract and verified identity, not merely the same vector length. If no valid From b065850025532b460f0e48b5e18de4b10231b6e2 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 3 Nov 2026 11:11:19 +0000 Subject: [PATCH 08/16] test: record frozen skill comparison without claiming tuning uplift --- docs/EVALUATION.md | 111 +++++++++++++++++ docs/evaluation/2026-11-03-aggregate.json | 80 ++++++++++++ docs/evaluation/2026-11-03-contexts.json | 85 +++++++++++++ docs/evaluation/2026-11-03-harness.json | 12 ++ tools/skill-eval/README.md | 82 +++++++++++++ tools/skill-eval/__init__.py | 1 + tools/skill-eval/adapter.py | 10 ++ tools/skill-eval/dataloader.py | 36 ++++++ tools/skill-eval/rollout.py | 141 ++++++++++++++++++++++ tools/skill-eval/run_eval.py | 126 +++++++++++++++++++ tools/skill-eval/test_harness.py | 49 ++++++++ 11 files changed, 733 insertions(+) create mode 100644 docs/EVALUATION.md create mode 100644 docs/evaluation/2026-11-03-aggregate.json create mode 100644 docs/evaluation/2026-11-03-contexts.json create mode 100644 docs/evaluation/2026-11-03-harness.json create mode 100644 tools/skill-eval/README.md create mode 100644 tools/skill-eval/__init__.py create mode 100644 tools/skill-eval/adapter.py create mode 100644 tools/skill-eval/dataloader.py create mode 100644 tools/skill-eval/rollout.py create mode 100644 tools/skill-eval/run_eval.py create mode 100644 tools/skill-eval/test_harness.py diff --git a/docs/EVALUATION.md b/docs/EVALUATION.md new file mode 100644 index 0000000..321c568 --- /dev/null +++ b/docs/EVALUATION.md @@ -0,0 +1,111 @@ +# VisionCraft evaluation evidence + +VisionCraft's packaging and source-retention checks are separate from evidence +that its guidance helps an agent make a useful decision. This report describes +one bounded, frozen comparison. It does not establish general coding quality, +a security guarantee, a production-readiness percentage or measured tuning +uplift. + +## Structural checks + +Candidate packaging retains a complete map of the 28 legacy skill paths. Its portable +payload contains 34 files, with file-level provenance, 73 resolved local Markdown +links, all thirteen Rust steering sections, seven byte-identical MIT Rust assets +and the complete inherited notice. Skill frontmatter validation passed. The +three AQE consumed-result schemas compiled under a strict JSON Schema validator; +input field names were checked against the pinned published MCP implementation. +Inherited lint assets loaded in an isolated dependency-free Clippy smoke +check on Rust 1.99.1. That check does not establish support for an older MSRV. + +## Frozen decision comparison + +An independently invoked Claude Sonnet 5.5 curator produced twelve synthetic +engineering handoff scenarios, split before execution into four training, four +validation and four held-out test cases. The scenarios ask for four bounded +choices: whether the stated evidence supports completion, the next action, +deployment observation status and review independence. The author/evaluator did +not inspect the held-out prompts or reference answers, and no candidate wording +was changed from their results. + +Target execution used the exact observed model `claude-haiku-4-5-20251001`, through +Claude CLI 2.1.309. Each invocation received four scenarios, shared rubric enum +definitions and one frozen guidance context. Reference answers and curator +rationales stayed in the private scorer. Tools and MCP were empty, settings +sources and session persistence were disabled, and each invocation used a fresh +empty working directory. Managed global instructions may still apply to both +arms; this is not an operating-system isolation experiment. + +| Context | Source revision | Bytes | Words | +|---|---|---:|---:| +| Canonical Agentbox baseline | `a9125eaf006e2679f5b81444c3c06d0fb45b7481` | 68,048 | 9,283 | +| Frozen VisionCraft candidate | `899e76600119a5159869551b374600d4cfb4a83e` | 37,149 | 5,119 | + +Each context contains six predeclared equivalent resources: entrypoint, EDD, +debugging, methodologies, review evidence and quality gates. No task-specific +trimming or retrieval was performed. Per-file hashes and exact context bytes +were retained. These different context lengths are a property of this comparison, +not a demonstrated token-efficiency improvement. Optional resources, runtime +adapters, actual coding, autonomous resource selection and deployed host tools +were not exercised by these classification tasks. + +Dataset SHA-256: +`2da88232856635de992c68417061acca664359508ba6a27df53a965809181340`. +Baseline context SHA-256: +`b54f6cc1a4b502a5165d0a2606062ecca4fccdf14dc3fc3ea10b548df17792e3`. +Candidate context SHA-256: +`043c48d4de9ebbc2beec7eb66ec8ad7b1baebba8806da027fc86aa82a77263ad`. + +## Scoring and result + +Each of four dimensions scores one when its label belongs to the curator's +accepted array. Hard accuracy requires all four labels; soft accuracy is the +fraction of matching dimensions. Invalid output, model unavailability and +execution errors remain distinct from valid wrong answers. A completed tool +call alone earns no task credit. + +Baseline training pilot scored 4/4 hard and 16/16 dimension decisions. This +is a saturated pilot, so no training loop or prose optimisation was attempted. +Remaining evaluation is a forward comparison of the already frozen rewrite. + +| Evaluation | Unique cases | Repetitions | Hard result | Soft result | +|---|---:|---:|---:|---:| +| Baseline training pilot | 4 | 1 | 4/4 | 16/16 | +| Candidate validation | 4 | 1 | 4/4 | 16/16 | +| Baseline held-out test | 4 | 3 | 12/12 case evaluations | 48/48 dimension decisions | +| Candidate held-out test | 4 | 3 | 12/12 case evaluations | 48/48 dimension decisions | + +All eight target calls completed using the requested model, without fallback, +timeout or invalid output. Each held-out repetition scored 100% hard and soft +for both contexts. No regression was observed on these four held-out scenarios. +This task is fully saturated and provides no evidence of an improvement over +the baseline. No training edits or further target calls were made. + +An [aggregate record](evaluation/2026-11-03-aggregate.json), +[context manifest](evaluation/2026-11-03-contexts.json) and +[execution-utility hashes](evaluation/2026-11-03-harness.json) are public. Raw +case material remains private. A later inline host-lint exception in the optional +AQE reference is outside these frozen contexts and is not an evaluated method +change. + +Three repetitions revisit the same four held-out cases. They measure variation +on those cases, not twelve independent examples. A small synthetic enum task can +miss important ambiguities and operational failures. A tie or high score here +cannot show that the skill improves real debugging, reviews or release work. +Future improvement claims need a harder independently curated training/validation +programme, relevant executed engineering tasks, and a new untouched test set. + +## Reproduction and retained evidence + +[The external evaluation utility](../tools/skill-eval/README.md) documents the +exact execution/scoring interface. It follows SkillOpt's batch-result and +per-item conversation convention but does not invoke an optimiser or add a +production dependency. Five synthetic fixture tests check answer isolation, +exact parsing, multi-answer acceptance, soft scoring and dataset validation. + +Private evidence retains curator output, the frozen dataset, contexts and hashes, +all raw target outputs, per-case conversations, usage/model metadata and scores. +Those scenario prompts, answers and conversations are deliberately not published +with this report. `aggregate.json` contains only aggregate results; the source +revisions and dataset hash allow an authorised custodian to reproduce or inspect +the comparison. Reusing a held-out set after editing from its answers would be a +new training exercise, not another independent test. diff --git a/docs/evaluation/2026-11-03-aggregate.json b/docs/evaluation/2026-11-03-aggregate.json new file mode 100644 index 0000000..c390ece --- /dev/null +++ b/docs/evaluation/2026-11-03-aggregate.json @@ -0,0 +1,80 @@ +{ + "groups": [ + { + "arm": "baseline", + "split": "test", + "attempts": 3, + "completed": 3, + "evaluations": 12, + "hard_acc": 1.0, + "soft_acc": 1.0, + "hard_replicates": [ + 1.0, + 1.0, + 1.0 + ], + "soft_replicates": [ + 1.0, + 1.0, + 1.0 + ], + "failures": [] + }, + { + "arm": "baseline", + "split": "train", + "attempts": 1, + "completed": 1, + "evaluations": 4, + "hard_acc": 1.0, + "soft_acc": 1.0, + "hard_replicates": [ + 1.0 + ], + "soft_replicates": [ + 1.0 + ], + "failures": [] + }, + { + "arm": "candidate", + "split": "test", + "attempts": 3, + "completed": 3, + "evaluations": 12, + "hard_acc": 1.0, + "soft_acc": 1.0, + "hard_replicates": [ + 1.0, + 1.0, + 1.0 + ], + "soft_replicates": [ + 1.0, + 1.0, + 1.0 + ], + "failures": [] + }, + { + "arm": "candidate", + "split": "val", + "attempts": 1, + "completed": 1, + "evaluations": 4, + "hard_acc": 1.0, + "soft_acc": 1.0, + "hard_replicates": [ + 1.0 + ], + "soft_replicates": [ + 1.0 + ], + "failures": [] + } + ], + "target_calls": 8, + "no_candidate_edits_during_comparison": true, + "test_prompts_or_answers_exposed_in_report": false, + "pilot_saturated": true +} diff --git a/docs/evaluation/2026-11-03-contexts.json b/docs/evaluation/2026-11-03-contexts.json new file mode 100644 index 0000000..e8dd9f0 --- /dev/null +++ b/docs/evaluation/2026-11-03-contexts.json @@ -0,0 +1,85 @@ +{ + "dataset_sha256": "2da88232856635de992c68417061acca664359508ba6a27df53a965809181340", + "arms": { + "baseline": { + "revision": "a9125eaf006e2679f5b81444c3c06d0fb45b7481", + "files": [ + { + "path": "skills/build-with-quality/SKILL.md", + "sha256": "4bfc807b6c5e518b5dc2847186f0503fb001c7061cf6a60851bbb4916afe6a53", + "bytes": 11174 + }, + { + "path": "skills/build-with-quality/EDD-PROTOCOL.md", + "sha256": "f403ca0cfbe4ec40962b3912050850a8ccd7daa9bb008f311501ab6ea17dd318", + "bytes": 19127 + }, + { + "path": "skills/build-with-quality/DEBUGGING-PROTOCOL.md", + "sha256": "e6f4997dd2c895d25e5754e3743f9ae8f88ae57a32289364b8f4602028fb5c7d", + "bytes": 10382 + }, + { + "path": "skills/build-with-quality/references/methodologies.md", + "sha256": "f06d08cd4e69d40739403a705287333f28800f126009bdff7334f72ebb2479d0", + "bytes": 5611 + }, + { + "path": "skills/build-with-quality/references/review-evidence.md", + "sha256": "d88fa12e3a91df6dba9975c6753e1594ddaf0a95e8f124163efbb6a3909c136d", + "bytes": 12830 + }, + { + "path": "skills/build-with-quality/references/quality-gates-and-workflow.md", + "sha256": "6f875f71a4bd62259c0c9608ef20b6ff1eb87931f9d016559dd90b05f7ec55ec", + "bytes": 8544 + } + ], + "context_sha256": "b54f6cc1a4b502a5165d0a2606062ecca4fccdf14dc3fc3ea10b548df17792e3", + "context_bytes": 68048, + "context_chars": 67106, + "context_words": 9283, + "selection": "Six predeclared equivalent method resources; no task-specific selection or truncation." + }, + "candidate": { + "revision": "899e76600119a5159869551b374600d4cfb4a83e", + "files": [ + { + "path": "skills/visioncraft/SKILL.md", + "sha256": "d081596856e07cfb0a8648c72807b839c75c4f35d8e7609b2f33af1aa827d426", + "bytes": 7156 + }, + { + "path": "skills/visioncraft/references/edd.md", + "sha256": "8585bed068204c385bade50b7bad9f39223a2b251760b6b9963dbba18d2992d7", + "bytes": 6616 + }, + { + "path": "skills/visioncraft/references/debugging.md", + "sha256": "ded614cf5a17e2ac3760cb8be93330ca370ccab06b6050c926370e3c627d1c94", + "bytes": 4702 + }, + { + "path": "skills/visioncraft/references/methodologies.md", + "sha256": "f537dac226f64a769622f7da13ed008d84e49d0988367cda6263eed15c34cc69", + "bytes": 3856 + }, + { + "path": "skills/visioncraft/references/review-evidence.md", + "sha256": "a3f5506c3cac1a0b75310a187955438b4cec9ae82794fc083bc7094616ee165b", + "bytes": 9047 + }, + { + "path": "skills/visioncraft/references/quality-gates.md", + "sha256": "44a63031a3848443efd8f0d9cad802187f6a424dcaefd9650e2c791023adba9c", + "bytes": 5443 + } + ], + "context_sha256": "043c48d4de9ebbc2beec7eb66ec8ad7b1baebba8806da027fc86aa82a77263ad", + "context_bytes": 37149, + "context_chars": 37129, + "context_words": 5119, + "selection": "Six predeclared equivalent method resources; no task-specific selection or truncation." + } + } +} diff --git a/docs/evaluation/2026-11-03-harness.json b/docs/evaluation/2026-11-03-harness.json new file mode 100644 index 0000000..9d152cf --- /dev/null +++ b/docs/evaluation/2026-11-03-harness.json @@ -0,0 +1,12 @@ +{ + "sha256": { + "test_harness.py": "6f697e2e32c01061caa90a46e8682e8f0cf581c96551e954fb0844bc119d29f6", + "adapter.py": "378183b4ba1030a7997e2eabdf827c79f8d2bbf8857a2ac1b14460f5156ccb9d", + "rollout.py": "908fcb14be1613d2e21a223dc0ae29ec62f5101d3738106581ec81ade4ef1329", + "__init__.py": "66c8591d32c0274329c9680f072eb128dd4720198e7012d44878947480b283c4", + "run_eval.py": "74e67e9b51f0c39962c94cf5a1c27c5f25120916119f7ab1d1079fbc08bbc0d1", + "dataloader.py": "dc1434f8e865c47888dfc0ffc2318b17eb5739ed3d4a5d46474e075cb83aa2a4" + }, + "cli_version": "2.1.309", + "scope": "All Python evaluation source files as executed; model prompts exclude accepted arrays and rationales." +} diff --git a/tools/skill-eval/README.md b/tools/skill-eval/README.md new file mode 100644 index 0000000..d865683 --- /dev/null +++ b/tools/skill-eval/README.md @@ -0,0 +1,82 @@ +# Frozen skill comparison utility + +This external Python utility checks a bounded set of engineering evidence +choices. It is not part of VisionCraft's runtime and does not install tools, +edit a skill, call the SkillOpt optimiser, or claim general coding quality. +It follows SkillOpt's batch-result and `predictions//conversation.json` +trajectory convention, so a separate training integration can consume those +artefacts. The held-out comparison itself uses the explicit runner below. + +Use Python 3.10+ and an already configured Claude CLI. The target is fixed to +`claude-haiku-4-5-20251001`; no fallback model is selected. Requests have no +available tools or MCP servers, disabled settings sources, a fresh empty working +directory, and no CLI session persistence. Managed global instructions may still +apply to both arms. This is tool-level isolation, not an operating-system sandbox. + +## Private dataset and public inputs + +Provide JSON with a shared `rubric` object and `items`. Each item contains a safe +`id`, `split` (`train`, `val` or `test`), `prompt`, and four `accepted` arrays: +`gate`, `next_action`, `deployment`, `independence`. This fixed comparison expects +four cases per split. Optional `answer_rationale` belongs only to the private +curator record. The loader passes only each item's ID and prompt, the four +shared rubric definitions, and enum vocabulary to the target. Reference arrays +and rationales never enter its prompt. + +Freeze the dataset and both skill revisions before the first call. The runner +extracts six predeclared equivalent method resources from each Git revision: +entrypoint, EDD, debugging, methodologies, review evidence and quality gates. +It retains exact file hashes, content sizes and combined context hashes. This +is a fixed-context method comparison, not a test of autonomous skill discovery. + +## Run phases in order + +Run the synthetic controls first: + +```sh +python3 -m unittest discover -s tools/skill-eval -p test_harness.py +``` + +Substitute actual paths and immutable revisions below. Run `pilot`, then +`validation`, then `test` as separate invocations; inspect only aggregate scores +until the held-out comparison has finished. A zero or perfect pilot signals +saturation, so this run cannot justify a tuning-uplift claim. + +```sh +python3 tools/skill-eval/run_eval.py \ + --dataset /private/evaluation/dataset.json \ + --baseline-repo /sources/agentbox --baseline-ref BASELINE_COMMIT \ + --candidate-repo /sources/visioncraft --candidate-ref CANDIDATE_COMMIT \ + --out /private/evaluation/frozen-comparison --phase pilot +``` + +Pilot execution uses baseline/train once; validation uses candidate/val once. The test +phase runs baseline/test and candidate/test three times each, with four cases +per invocation. Maximum concurrency is two and each invocation has a 180-second +deadline. A serial phase reservation ledger bounds this programme to ten calls, +including unsuccessful attempts. Eight calls are scheduled; no retries or +implicit follow-up calls are made. Run phases from one process at a time. +An unavailable pilot or validation stops progression to test. + +Each call retains its exact request, raw CLI output, stderr, observed model, +usage fields when supplied, elapsed time and per-case conversations. Those +files contain private scenarios and must not be committed or published. Local +score rows follow SkillOpt's `id`, `hard`, `soft`, `task_description`, +`fail_reason`, `n_turns` convention. A batched CLI call is one execution shared +by four cases, not four independently executed conversations. + +## Scoring and limits + +A dimension scores one when the predicted label belongs to its accepted array. +Hard score is one only when all four dimensions match; soft score is their +fraction. Malformed, duplicate, missing or unknown answers are invalid outputs. +Model errors, unavailable/unverified models and timeouts are separately labelled +and excluded from completed-performance aggregates. They are not evidence that +one skill solved no tasks. + +`aggregate.json` contains no prompts or reference answers. Replication measures +stochastic variation on the same four held-out cases; it does not create twelve +independent scenarios. No skill may be edited from those answers and then be +reported as evaluated by the same held-out test. A new candidate needs a fresh, +independently curated test set. Document context-length differences, scope, +curator/model identities, unavailable calls and the exact source revisions. diff --git a/tools/skill-eval/__init__.py b/tools/skill-eval/__init__.py new file mode 100644 index 0000000..ce629a9 --- /dev/null +++ b/tools/skill-eval/__init__.py @@ -0,0 +1 @@ +"""Standalone evaluation adapter; no production dependency or automatic model call.""" diff --git a/tools/skill-eval/adapter.py b/tools/skill-eval/adapter.py new file mode 100644 index 0000000..5e9b37a --- /dev/null +++ b/tools/skill-eval/adapter.py @@ -0,0 +1,10 @@ +"""Thin external batch adapter compatible with SkillOpt's result/trajectory contract.""" +from pathlib import Path +from rollout import run_batch + +def run_visioncraft_batch(*, data, items, skill_content, out_dir, **kwargs): + """Return per-item id/hard/soft/task_description/fail_reason/n_turns rows.""" + import json + path = Path(out_dir) + run_batch(data, list(items), skill_content, path, **kwargs) + return json.loads((path / 'results-private.json').read_text()) diff --git a/tools/skill-eval/dataloader.py b/tools/skill-eval/dataloader.py new file mode 100644 index 0000000..7d0164e --- /dev/null +++ b/tools/skill-eval/dataloader.py @@ -0,0 +1,36 @@ +"""Private scenario loader; never print reference answers or held-out prompts.""" +from __future__ import annotations +import json +from pathlib import Path + +DIMENSIONS = ('gate', 'next_action', 'deployment', 'independence') +ENUMS = { + 'gate': ('pass', 'blocked', 'incomplete', 'invalid'), + 'next_action': ('execute', 'fix_setup', 'fix_code', 'review_evidence', 'update_docs', 'ship_source', 'request_required_input'), + 'deployment': ('observed', 'unobserved', 'contradicted'), + 'independence': ('satisfied', 'degraded', 'not_required', 'unknown'), +} + +def load_dataset(path: Path) -> dict: + data = json.loads(path.read_text()) + assert isinstance(data['rubric'], dict) + ids = set() + for item in data['items']: + assert isinstance(item['id'], str) and item['id'] and item['id'] not in ids + assert all(c.isalnum() or c in '-_' for c in item['id']) + ids.add(item['id']) + assert item['split'] in ('train', 'val', 'test') + assert isinstance(item['prompt'], str) and item['prompt'] + for name in DIMENSIONS: + values = item['accepted'][name] + assert isinstance(values, list) and values + assert all(value in ENUMS[name] for value in values) + return data + +def public_batch(data: dict, items: list[dict]) -> dict: + """Expose only task prose and the curator's shared dimension definitions.""" + return { + 'rubric': {name: data['rubric'][name] for name in DIMENSIONS}, + 'allowed_values': ENUMS, + 'items': [{'id': item['id'], 'prompt': item['prompt']} for item in items], + } diff --git a/tools/skill-eval/rollout.py b/tools/skill-eval/rollout.py new file mode 100644 index 0000000..817dfd2 --- /dev/null +++ b/tools/skill-eval/rollout.py @@ -0,0 +1,141 @@ +"""Bounded, no-tool Claude rollout and deterministic SkillOpt-shaped scoring. + +This is an external evaluation utility, not part of VisionCraft's runtime. +Reference answers stay in the caller's private dataset and scorer. +""" +from __future__ import annotations +import hashlib +import json +import os +from pathlib import Path +import signal +import subprocess +import time +from dataloader import DIMENSIONS, ENUMS, public_batch + +TARGET_MODEL = 'claude-haiku-4-5-20251001' + +def sha256(data: bytes) -> str: + return hashlib.sha256(data).hexdigest() + +def write_json(path: Path, value: object) -> None: + path.write_text(json.dumps(value, indent=2, ensure_ascii=False) + '\n') + +def prompt_for(data: dict, items: list[dict], skill: str) -> str: + task = public_batch(data, items) + return ( + 'Apply the supplied engineering guidance to each independent scenario. ' + 'Do not use tools or read files. Use only facts stated in each scenario; ' + 'do not assume extra requirements or successful executions. ' + 'Return one JSON object with key answers, an array containing exactly ' + 'one object per item: id, gate, next_action, deployment, independence. ' + 'Use the provided exact enum values. Do not include explanations.\n\n' + '\n' + skill + '\n\n\n' + + json.dumps(task, ensure_ascii=False) + ) + +def parse_predictions(text: str, items: list[dict]) -> dict: + value = text.strip() + if value.startswith('```json') and value.endswith('```'): + value = value[len('```json'):-3].strip() + elif value.startswith('```') and value.endswith('```'): + value = value[3:-3].strip() + parsed = json.loads(value) + assert set(parsed) == {'answers'} and isinstance(parsed['answers'], list) + expected = {item['id'] for item in items} + answers = {} + for row in parsed['answers']: + assert set(row) == {'id', *DIMENSIONS} + assert row['id'] in expected and row['id'] not in answers + assert all(row[name] in ENUMS[name] for name in DIMENSIONS) + answers[row['id']] = row + assert set(answers) == expected + return answers + +def score_item(item: dict, answer: dict | None, failure: str = '') -> dict: + dimensions = {name: bool(answer and answer[name] in item['accepted'][name]) for name in DIMENSIONS} + return { + 'id': item['id'], 'hard': int(all(dimensions.values())), + 'soft': sum(dimensions.values()) / len(DIMENSIONS), + 'dimensions': dimensions, 'fail_reason': failure, + 'task_description': item['prompt'], 'n_turns': 1 if answer else 0, + } + +def run_batch(data: dict, items: list[dict], skill: str, out_dir: Path, + model: str = TARGET_MODEL, timeout: int = 180) -> dict: + """Run one four-case batch; retain private raw output and per-item trajectories.""" + assert model == TARGET_MODEL and 1 <= timeout <= 180 and len(items) == 4 + out_dir.mkdir(parents=True, exist_ok=False) + sandbox = out_dir / 'empty-cwd' + sandbox.mkdir() + prompt = prompt_for(data, items, skill) + (out_dir / 'prompt-private.txt').write_text(prompt) + args = ['claude', '-p', '--model', model, '--tools', '', '--strict-mcp-config', + '--mcp-config', '{"mcpServers":{}}', '--setting-sources', '', + '--no-session-persistence', '--output-format', 'json', '--max-turns', '2'] + started = time.time() + process = subprocess.Popen(args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, + stderr=subprocess.PIPE, text=True, cwd=sandbox, + start_new_session=True) + timed_out = False + try: + stdout, stderr = process.communicate(prompt, timeout=timeout) + except subprocess.TimeoutExpired: + timed_out = True + os.killpg(process.pid, signal.SIGTERM) + try: + stdout, stderr = process.communicate(timeout=3) + except subprocess.TimeoutExpired: + os.killpg(process.pid, signal.SIGKILL) + stdout, stderr = process.communicate(timeout=3) + (out_dir / 'raw-private.json').write_text(stdout) + (out_dir / 'stderr-private.log').write_text(stderr) + outer, answers, failure = {}, {}, '' + if timed_out: + failure = 'target_timeout' + elif process.returncode != 0: + failure = 'target_exit_error' + else: + try: + outer = json.loads(stdout) + if outer.get('is_error') is True: + failure = 'target_reported_error' + else: + observed = list(outer.get('modelUsage', {})) + if not observed or any(name != model for name in observed): + failure = 'target_model_unverified' + else: + answers = parse_predictions(outer['result'], items) + except (ValueError, KeyError, TypeError, AssertionError): + failure = 'invalid_target_response' + results = [] + for item in items: + answer = answers.get(item['id']) + score = score_item(item, answer, failure) + results.append(score) + pred = out_dir / 'predictions' / item['id'] + pred.mkdir(parents=True) + write_json(pred / 'conversation.json', [ + {'role': 'user', 'content': prompt_for(data, [item], skill)}, + {'role': 'assistant', 'content': json.dumps(answer) if answer else ''}, + {'role': 'system', 'content': json.dumps({k: score[k] for k in ('hard', 'soft', 'dimensions', 'fail_reason')})}, + ]) + write_json(pred / 'prediction.json', answer) + # Results contain task prose for SkillOpt compatibility; keep them private. + write_json(out_dir / 'results-private.json', results) + meta = { + 'status': 'unavailable' if failure else 'completed', 'failure': failure, + 'model_requested': model, 'models_observed': list(outer.get('modelUsage', {})), + 'argv': args, 'cwd_policy': 'fresh empty directory; tools/MCP/settings disabled; managed global instructions may still apply', + 'elapsed_s': round(time.time() - started, 3), 'rc': process.returncode, + 'prompt_sha256': sha256(prompt.encode()), 'prompt_bytes': len(prompt.encode()), + 'raw_output_sha256': sha256(stdout.encode()), 'item_count': len(items), + 'hard_acc': sum(row['hard'] for row in results) / len(results), + 'soft_acc': sum(row['soft'] for row in results) / len(results), + 'dimension_acc': {name: sum(row['dimensions'][name] for row in results) / len(results) for name in DIMENSIONS}, + 'usage': outer.get('usage'), 'model_usage': outer.get('modelUsage'), + 'reported_cost_usd': outer.get('total_cost_usd'), + 'count_boundary': 'Unavailable/invalid calls are not evidence of task performance; their scores are retained only for diagnosis.', + } + write_json(out_dir / 'meta.json', meta) + return meta diff --git a/tools/skill-eval/run_eval.py b/tools/skill-eval/run_eval.py new file mode 100644 index 0000000..6b38de2 --- /dev/null +++ b/tools/skill-eval/run_eval.py @@ -0,0 +1,126 @@ +#!/usr/bin/env python3 +"""Replicate a frozen skill comparison; print aggregates, never private cases.""" +from __future__ import annotations +import argparse +from concurrent.futures import ThreadPoolExecutor +import json +from pathlib import Path +import subprocess +from dataloader import load_dataset +from rollout import run_batch, sha256, write_json + +BASE_FILES = [ + 'skills/build-with-quality/SKILL.md', + 'skills/build-with-quality/EDD-PROTOCOL.md', + 'skills/build-with-quality/DEBUGGING-PROTOCOL.md', + 'skills/build-with-quality/references/methodologies.md', + 'skills/build-with-quality/references/review-evidence.md', + 'skills/build-with-quality/references/quality-gates-and-workflow.md', +] +CANDIDATE_FILES = [ + 'skills/visioncraft/SKILL.md', + 'skills/visioncraft/references/edd.md', + 'skills/visioncraft/references/debugging.md', + 'skills/visioncraft/references/methodologies.md', + 'skills/visioncraft/references/review-evidence.md', + 'skills/visioncraft/references/quality-gates.md', +] + +def git(repo: Path, *args: str) -> bytes: + return subprocess.check_output(['git', '-C', str(repo), *args]) + +def freeze_context(repo: Path, revision: str, paths: list[str], destination: Path) -> tuple[str, dict]: + commit = git(repo, 'rev-parse', revision + '^{commit}').decode().strip() + parts, files = [], [] + for path in paths: + raw = git(repo, 'show', f'{commit}:{path}') + parts.append(f'\n===== {path} =====\n' + raw.decode()) + files.append({'path': path, 'sha256': sha256(raw), 'bytes': len(raw)}) + context = ''.join(parts) + manifest = {'revision': commit, 'files': files, 'context_sha256': sha256(context.encode()), + 'context_bytes': len(context.encode()), 'context_chars': len(context), + 'context_words': len(context.split()), 'selection': 'Six predeclared equivalent method resources; no task-specific selection or truncation.'} + if destination.exists(): + assert destination.read_text() == context, 'frozen context changed' + else: + destination.write_text(context) + return context, manifest + +def aggregate(out: Path) -> dict: + groups = {} + for path in sorted((out / 'runs').glob('*/meta.json')): + meta = json.loads(path.read_text()) + arm, split, rep = path.parent.name.split('__') + groups.setdefault((arm, split), []).append(meta) + rows = [] + for (arm, split), metas in sorted(groups.items()): + complete = [m for m in metas if m['status'] == 'completed'] + rows.append({'arm': arm, 'split': split, 'attempts': len(metas), 'completed': len(complete), + 'evaluations': sum(m['item_count'] for m in complete), + 'hard_acc': sum(m['hard_acc'] for m in complete) / len(complete) if complete else None, + 'soft_acc': sum(m['soft_acc'] for m in complete) / len(complete) if complete else None, + 'hard_replicates': [m['hard_acc'] for m in complete], + 'soft_replicates': [m['soft_acc'] for m in complete], + 'failures': [m['failure'] for m in metas if m['failure']]}) + result = {'groups': rows, 'target_calls': sum(r['attempts'] for r in rows), + 'no_candidate_edits_during_comparison': True, + 'test_prompts_or_answers_exposed_in_report': False} + pilot = next((r for r in rows if r['arm'] == 'baseline' and r['split'] == 'train'), None) + result['pilot_saturated'] = bool(pilot and pilot['completed'] and pilot['hard_acc'] in (0, 1)) + write_json(out / 'aggregate.json', result) + return result + +def main() -> None: + p = argparse.ArgumentParser(description=__doc__) + p.add_argument('--dataset', type=Path, required=True) + p.add_argument('--baseline-repo', type=Path, required=True) + p.add_argument('--baseline-ref', required=True) + p.add_argument('--candidate-repo', type=Path, required=True) + p.add_argument('--candidate-ref', required=True) + p.add_argument('--out', type=Path, required=True) + p.add_argument('--phase', choices=['pilot', 'validation', 'test', 'summary'], required=True) + args = p.parse_args() + args.out = args.out.resolve() + args.out.mkdir(parents=True, exist_ok=True) + data = load_dataset(args.dataset) + assert all(sum(i['split'] == s for i in data['items']) == 4 for s in ('train', 'val', 'test')) + contexts, manifest = {}, {'dataset_sha256': sha256(args.dataset.read_bytes()), 'arms': {}} + for arm, repo, ref, files in [('baseline', args.baseline_repo, args.baseline_ref, BASE_FILES), + ('candidate', args.candidate_repo, args.candidate_ref, CANDIDATE_FILES)]: + contexts[arm], manifest['arms'][arm] = freeze_context(repo, ref, files, args.out / f'{arm}-context.txt') + mp = args.out / 'context-manifest.json' + if mp.exists(): + assert json.loads(mp.read_text()) == manifest, 'dataset/context manifest changed' + else: + write_json(mp, manifest) + (args.out / 'runs').mkdir(exist_ok=True) + phases = {'pilot': [('baseline', 'train', 1)], 'validation': [('candidate', 'val', 1)], + 'test': [(arm, 'test', rep) for rep in range(1, 4) for arm in ('baseline', 'candidate')], + 'summary': []} + jobs = phases[args.phase] + if args.phase in ('validation', 'test'): + pilot = args.out / 'runs/baseline__train__1/meta.json' + assert pilot.exists() and json.loads(pilot.read_text())['status'] == 'completed', 'pilot unavailable; no target fallback' + if args.phase == 'test': + val = args.out / 'runs/candidate__val__1/meta.json' + assert val.exists() and json.loads(val.read_text())['status'] == 'completed', 'validation unavailable; stop before test' + # The external caller runs phases serially. Reservations count failures too; + # no retry or model fallback occurs, and no public command reads the answers. + reservations = args.out / 'call-reservations.json' + used = json.loads(reservations.read_text()) if reservations.exists() else [] + assert len(used) + len(jobs) <= 10, 'ten-call budget exhausted' + labels = [f'{a}__{s}__{r}' for a, s, r in jobs] + assert not set(labels) & set(used), 'refusing to rerun a reserved batch' + write_json(reservations, used + labels) + def execute(job): + arm, split, rep = job + items = [i for i in data['items'] if i['split'] == split] + meta = run_batch(data, items, contexts[arm], args.out / 'runs' / f'{arm}__{split}__{rep}') + return {'arm': arm, 'split': split, 'rep': rep, **{k:meta[k] for k in ('status','failure','models_observed','hard_acc','soft_acc','elapsed_s')}} + with ThreadPoolExecutor(max_workers=2) as pool: + for result in pool.map(execute, jobs): + print(json.dumps(result), flush=True) + print(json.dumps(aggregate(args.out)), flush=True) + +if __name__ == '__main__': + main() diff --git a/tools/skill-eval/test_harness.py b/tools/skill-eval/test_harness.py new file mode 100644 index 0000000..ae55766 --- /dev/null +++ b/tools/skill-eval/test_harness.py @@ -0,0 +1,49 @@ +"""Synthetic controls for leakage boundaries, parsing and four-dimension scores.""" +import json +from pathlib import Path +import tempfile +import unittest +from dataloader import DIMENSIONS, load_dataset, public_batch +from rollout import parse_predictions, prompt_for, score_item + + +def fixture(): + answer = {'gate':'pass','next_action':'execute','deployment':'unobserved','independence':'not_required'} + item = {'id':'synthetic-1','split':'train','prompt':'Synthetic task, no private evaluation item.', + 'accepted':{k:[v] for k,v in answer.items()},'answer_rationale':'SECRET_REFERENCE_MARKER'} + data = {'rubric':{k:{'definition':'Shared enum definition'} for k in DIMENSIONS},'items':[item]} + return data,item,{'id':item['id'],**answer} + +class HarnessTest(unittest.TestCase): + def test_answers_never_enter_target_prompt(self): + data,item,_=fixture() + public=public_batch(data,[item]) + self.assertEqual(set(public['items'][0]),{'id','prompt'}) + rendered=prompt_for(data,[item],'Frozen guidance') + self.assertNotIn('SECRET_REFERENCE_MARKER',rendered) + self.assertNotIn('"accepted"',rendered) + self.assertNotIn('answer_rationale',rendered) + def test_exact_response_and_multiple_accepted_values(self): + _,item,answer=fixture() + item['accepted']['next_action'].append('review_evidence') + answer['next_action']='review_evidence' + parsed=parse_predictions(json.dumps({'answers':[answer]}),[item]) + self.assertEqual(score_item(item,parsed[item['id']])['hard'],1) + def test_soft_fraction_and_missing_response(self): + _,item,answer=fixture() + answer['deployment']='observed' + score=score_item(item,answer) + self.assertEqual((score['hard'],score['soft']),(0,0.75)) + self.assertEqual(score_item(item,None,'unavailable')['soft'],0) + def test_duplicate_unknown_and_missing_rows_rejected(self): + _,item,answer=fixture() + for rows in ([answer,answer],[],[{**answer,'extra':'pass'}],[{**answer,'gate':'green'}]): + with self.assertRaises(AssertionError): + parse_predictions(json.dumps({'answers':rows}),[item]) + def test_loader_validates_and_does_not_print(self): + data,_,_=fixture() + with tempfile.TemporaryDirectory() as d: + p=Path(d)/'synthetic.json';p.write_text(json.dumps(data)) + self.assertEqual(load_dataset(p),data) + +if __name__=='__main__': unittest.main() From 60e42fa72e21031b90f5a62cac320758bba3f6f6 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 3 Nov 2026 11:13:13 +0000 Subject: [PATCH 09/16] Bound source inspection and verify native evidence workflows --- examples/native-workflow.md | 87 ++++++++++++++ src/cli.rs | 233 +++++++++++++++++++++++++++++------- tests/native_cli.rs | 213 ++++++++++++++++++++++++++++++++ 3 files changed, 487 insertions(+), 46 deletions(-) create mode 100644 examples/native-workflow.md diff --git a/examples/native-workflow.md b/examples/native-workflow.md new file mode 100644 index 0000000..1a8a379 --- /dev/null +++ b/examples/native-workflow.md @@ -0,0 +1,87 @@ +# Capture, run and evaluate a bounded check + +Run from a committed Git worktree. Choose the source, locks and configuration +that determine the behaviour you intend to check; the CLI does not infer a +complete dependency closure from the command name. + +```sh +visioncraft plan init --out quality-plan.json \ + --input Cargo.toml --input Cargo.lock \ + --configuration 'library, default features disabled' \ + --timeout-ms 600000 --max-output-bytes 8388608 \ + -- cargo test --locked --no-default-features + +visioncraft plan check quality-plan.json --json +visioncraft run quality-plan.json --all --out .visioncraft/run-001 +visioncraft evaluate quality-plan.json --receipts .visioncraft/run-001 --json +``` + +The program and arguments after `--` are literal argv. Invoke another installed +quality tool the same way, using its current documented command and selected +source inputs. VisionCraft does not add a shell, infer model runtime support or +interpret an upstream result as a stronger claim than its declared evaluator. + +`plan init` writes one required exit-code check. Its defaults are a 60-second +deadline, 8 MiB combined output, `PATH` as the only inherited environment name +and a 30-day maximum evidence age. Choose bounds and environment names explicitly +for the real check. Program lookup uses that PATH when selected, otherwise +`/usr/bin:/bin`; resolved executable identity and its hash, when readable, are +recorded separately from the requested program. Commands retain the invoking +user's authority: this is not a sandbox. + +An edited selected input produces a private adjacent +`.quality-plan.json.evidence/selected-inputs.json` snapshot containing the exact +selected bytes. That directory and run directories are gitignored before raw +capture. Keep the snapshot beside the plan until execution; the runner copies it +into the evidence root. Clean plans need no dirty snapshot. Reusing output +directories is refused. Source, evidence and managed output paths reject nested +symlinks after resolving the explicitly chosen source/evidence root. + +`run` records selected invocations. Its exit code does not claim the whole plan +passed: `evaluate` applies every required check and expectation. All required +receipts must be supplied, with one selected attempt per check. Preserve older +attempts separately and name multiple `--receipts` directories when combining +different selected checks. `gate evaluate` and `expectations check` use the same +whole-plan evaluation; neither hides another required check's failure. + +The native runner records actual stdout, stderr, exit/signal, before/after source +hashes and elapsed time. It leaves `observed_scope` unknown and `observed_tests` +empty. Selecting files or putting a test name in argv does not prove what the +tool inspected or executed. Plans requiring observed coverage or a stabiliser +therefore need a real tool-specific observation/adapter. `reported` evaluators +must use their named adapter; generic `run` refuses to invent that assessment. + +An optional `--context context.json` supplies the core's `AuditReceipt` and +`ManualObservation` records plus explicit model-family aliases: + +```json +{ + "audits": [], + "manual_observations": [], + "families": [{"route": "local:reviewer-alias", "family": "anthropic"}] +} +``` + +Artifact references in this context resolve relative to its parent directory. +Use the public Rust type documentation for the complete audit/manual fields. +Empty arrays do not satisfy an expectation that requires those observations. +Sealmap checks family declarations; a new provider label does not make a model +independent. `--current-subject` can supply a subject record, but the CLI checks +it against actual selected source bytes and the current Git revision before use. + +Evaluation reads evidence and fixed Git metadata operations; it never runs +commands found in plans or receipts. It compares unfiltered committed blobs and +selected current bytes rather than invoking repository clean filters. A later +unrelated commit can retain fresh evidence when ancestry and selected bytes +match; changed or missing selected inputs cannot borrow the old pass. The +optional `--as-of-ms` clock is for explicit reproducible evaluations, not a claim +that old evidence was captured again. + +Each Git metadata operation uses the same bounded process runner with a +10-second deadline and private temporary captures. Committed blob size is +checked before requesting its contents. Ambient `GIT_DIR`/`GIT_WORK_TREE` are +excluded, lazy fetching is disabled, and cancellation stops inspection too. + +For review findings and independent delivery stages, retain the immutable raw +export and use `sealmap review init/check/summary`. VisionCraft does not create a +second disposition store or infer deployment from a test or publication result. diff --git a/src/cli.rs b/src/cli.rs index a8c5169..0f658e9 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -8,7 +8,6 @@ use std::collections::BTreeSet; use std::fs::{self, File}; use std::io::{Read, Write}; use std::path::{Component, Path, PathBuf}; -use std::process::{Command, Stdio}; use std::sync::atomic::AtomicBool; use std::time::{SystemTime, UNIX_EPOCH}; @@ -63,7 +62,7 @@ enum Operation { #[derive(Debug, Subcommand)] enum PlanCommand { /// Capture selected source bytes into a plan for one explicit argv check. - Init(InitOptions), + Init(Box), /// Validate a plan schema and policy; no recorded commands are run. Check { plan: PathBuf, @@ -331,47 +330,112 @@ fn print_json(value: &impl Serialize) -> Result<(), CliError> { .map_err(io_error) } -fn git(root: &Path, args: &[&str]) -> Result { - Command::new("git") - .args([ - "--no-pager", - "--literal-pathspecs", - "-c", - "core.fsmonitor=false", - "-c", - "core.untrackedCache=false", - "-C", - ]) - .arg(root) - .args(args) - .env("GIT_OPTIONAL_LOCKS", "0") - .env("GIT_NO_LAZY_FETCH", "1") - .env("GIT_NO_REPLACE_OBJECTS", "1") - .env("GIT_TERMINAL_PROMPT", "0") - .stdin(Stdio::null()) - .output() - .map_err(io_error) +struct GitOutput { + success: bool, + stdout: Vec, } -fn revision(root: &Path) -> Result { - let output = git(root, &["rev-parse", "--verify", "HEAD"])?; +fn git(root: &Path, args: &[&str], cancelled: &AtomicBool) -> Result { + let mut temporary = tempfile::Builder::new(); + temporary.prefix("visioncraft-inspection-"); + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + temporary.permissions(fs::Permissions::from_mode(0o700)); + } + let temporary = temporary.tempdir().map_err(io_error)?; + let limit = if args.first() == Some(&"cat-file") && args.get(1) == Some(&"blob") { + MAX_FILE + } else { + MAX_JSON + }; + let mut argv: Vec = [ + "--no-pager", + "--literal-pathspecs", + "-c", + "core.fsmonitor=false", + "-c", + "core.untrackedCache=false", + "-C", + ] + .into_iter() + .map(str::to_owned) + .collect(); + argv.push( + root.to_str() + .ok_or_else(|| { + error( + 78, + "source root is not representable in portable invocation metadata", + ) + })? + .into(), + ); + argv.extend(args.iter().map(|arg| (*arg).to_owned())); + let fixed: std::collections::BTreeMap = [ + ("GIT_OPTIONAL_LOCKS", "0"), + ("GIT_NO_LAZY_FETCH", "1"), + ("GIT_NO_REPLACE_OBJECTS", "1"), + ("GIT_TERMINAL_PROMPT", "0"), + ("GIT_CONFIG_NOSYSTEM", "1"), + ("GIT_CONFIG_GLOBAL", "/dev/null"), + ] + .into_iter() + .map(|(name, value)| (name.into(), value.into())) + .collect(); + let mut env = vec!["PATH".into()]; + env.extend(fixed.keys().cloned()); + let invocation = Invocation { + program: "git".into(), + args: argv, + cwd: ".".into(), + env, + timeout_ms: 10_000, + max_output_bytes: limit, + }; + let captured = process::run_command_with_env( + &invocation, + root, + temporary.path(), + cancelled, + false, + &fixed, + ) + .map_err(io_error)?; + match captured.termination { + Termination::Completed if captured.exit_code.is_some() => Ok(GitOutput { + success: captured.exit_code == Some(0), + stdout: read_bounded(&captured.stdout, limit)?, + }), + Termination::Unavailable => Err(error(78, "Git metadata inspector is unavailable")), + Termination::TimedOut => Err(error(124, "Git metadata inspection exceeded its deadline")), + Termination::Interrupted => Err(error(130, "Git metadata inspection interrupted")), + _ => Err(error( + 70, + "Git metadata inspection failed or exceeded its capture bound", + )), + } +} + +fn revision(root: &Path, cancelled: &AtomicBool) -> Result { + let output = git(root, &["rev-parse", "--verify", "HEAD"], cancelled)?; let revision = String::from_utf8(output.stdout) .map_err(|_| error(2, "Git revision is not UTF-8"))? .trim() .to_owned(); - if !output.status.success() || !crate::hex(&revision, &[40, 64]) { + if !output.success || !crate::hex(&revision, &[40, 64]) { return Err(error(2, "source root requires a committed Git revision")); } Ok(revision) } -fn selected_dirty(root: &Path, paths: &[String]) -> Result { +fn selected_dirty(root: &Path, paths: &[String], cancelled: &AtomicBool) -> Result { // Git status/diff may invoke configured clean filters. Compare unfiltered // committed blob bytes instead; worktree conversion differences are dirty. let mut args = vec!["ls-tree", "-z", "--full-tree", "HEAD", "--"]; args.extend(paths.iter().map(String::as_str)); - let output = git(root, &args)?; - if !output.status.success() { + let output = git(root, &args, cancelled)?; + if !output.success { return Err(error(70, "could not inspect selected Git input status")); } let mut entries = std::collections::BTreeMap::new(); @@ -401,16 +465,31 @@ fn selected_dirty(root: &Path, paths: &[String]) -> Result { if !crate::hex(object, &[40, 64]) { return Err(error(70, "invalid Git object identifier")); } - let blob = git(root, &["cat-file", "blob", object])?; - if !blob.status.success() { + let size = git(root, &["cat-file", "-s", object], cancelled)?; + let declared = std::str::from_utf8(&size.stdout) + .map_err(|_| error(70, "invalid committed blob size"))? + .trim(); + if !size.success || !declared.bytes().all(|b| b.is_ascii_digit()) { + return Err(error(70, "committed blob size is unavailable")); + } + let declared = declared + .parse::() + .map_err(|_| error(70, "invalid committed blob size"))?; + if declared > MAX_FILE { + return Err(error(2, "committed source blob exceeds inspection bound")); + } + let blob = git(root, &["cat-file", "blob", object], cancelled)?; + if !blob.success || blob.stdout.len() as u64 != declared { return Err(error(70, "committed source blob is unavailable")); } + let committed_hash = crate::sha256(&blob.stdout); + drop(blob); let current = match confined(root, path, false) { Ok(file) => read_bounded(&file, MAX_FILE)?, Err(_) if !root.join(path).try_exists().map_err(io_error)? => return Ok(true), Err(e) => return Err(e), }; - if blob.stdout != current { + if committed_hash != crate::sha256(¤t) { return Ok(true); } } @@ -495,7 +574,7 @@ fn read_plan(path: &Path) -> Result<(PathBuf, QualityPlan), CliError> { Ok((parent, QualityPlan::parse(&bytes).map_err(invalid)?)) } -fn init(options: InitOptions) -> Result { +fn init(options: InitOptions, cancelled: &AtomicBool) -> Result { let root = root(&options.root)?; let out = output_path(&options.out)?; let mut paths = options.input; @@ -508,9 +587,9 @@ fn init(options: InitOptions) -> Result { return Err(error(2, "input paths must be relative")); } } - let revision = revision(&root)?; + let revision = revision(&root, cancelled)?; let selected = inputs(&root, &paths, false)?; - let dirty = selected_dirty(&root, &paths)?; + let dirty = selected_dirty(&root, &paths, cancelled)?; let snapshot = if dirty { Some(source_snapshot(&root, &paths, &revision, &selected)?) } else { @@ -648,6 +727,48 @@ fn execution_exit(receipt: &ExecutionReceipt, evaluator: &Evaluator) -> i32 { } } +fn executable(invocation: &Invocation, source_root: &Path) -> Option { + let requested = Path::new(&invocation.program); + let candidates = if requested.is_absolute() { + vec![requested.to_owned()] + } else if requested.components().count() > 1 { + vec![source_root.join(&invocation.cwd).join(requested)] + } else { + // Make PATH resolution explicit so the receipt can name the binary + // actually selected, independently of the requested program spelling. + let search = if invocation.env.iter().any(|name| name == "PATH") { + std::env::var_os("PATH").unwrap_or_else(|| "/usr/bin:/bin".into()) + } else { + "/usr/bin:/bin".into() + }; + std::env::split_paths(&search) + .map(|directory| { + let directory = if directory.is_absolute() { + directory + } else { + source_root.join(&invocation.cwd).join(directory) + }; + directory.join(requested) + }) + .collect() + }; + candidates.into_iter().find_map(|path| { + let path = path.canonicalize().ok()?; + let metadata = fs::metadata(&path).ok()?; + if !metadata.is_file() { + return None; + } + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + if metadata.permissions().mode() & 0o111 == 0 { + return None; + } + } + Some(path) + }) +} + fn run(options: RunOptions, cancelled: &AtomicBool) -> Result { let source_root = root(&options.root)?; let (plan_root, plan) = read_plan(&options.plan)?; @@ -669,7 +790,7 @@ fn run(options: RunOptions, cancelled: &AtomicBool) -> Result { confined(&source_root, &check.invocation.cwd, true)?; } let paths: Vec<_> = plan.subject.inputs.iter().map(|a| a.path.clone()).collect(); - if revision(&source_root)? != plan.subject.revision + if revision(&source_root, cancelled)? != plan.subject.revision || inputs(&source_root, &paths, false)? != plan.subject.inputs { return Err(error( @@ -696,7 +817,7 @@ fn run(options: RunOptions, cancelled: &AtomicBool) -> Result { let mut exit = 0; for (index, check) in selected.into_iter().enumerate() { if inputs(&source_root, &paths, false)? != plan.subject.inputs - || revision(&source_root)? != plan.subject.revision + || revision(&source_root, cancelled)? != plan.subject.revision { return Err(error( 1, @@ -707,8 +828,26 @@ fn run(options: RunOptions, cancelled: &AtomicBool) -> Result { let directory = format!("check-{index:04}"); let attempt = out.join(&directory); process::private_directory(&attempt).map_err(io_error)?; + let resolved = executable(&check.invocation, &source_root); + if resolved + .as_ref() + .is_some_and(|path| path.to_str().is_none()) + { + return Err(error( + 78, + "resolved executable path is not representable in the portable receipt", + )); + } + let executable_sha256 = resolved + .as_ref() + .and_then(|path| read_bounded(path, MAX_FILE).ok()) + .map(|bytes| crate::sha256(&bytes)); + let mut actual_invocation = check.invocation.clone(); + if let Some(path) = &resolved { + actual_invocation.program = path.to_string_lossy().into_owned(); + } let captured = - process::run_command(&check.invocation, &source_root, &attempt, cancelled, false) + process::run_command(&actual_invocation, &source_root, &attempt, cancelled, false) .map_err(io_error)?; let stdout = Artifact { path: format!("{directory}/stdout.log"), @@ -747,8 +886,10 @@ fn run(options: RunOptions, cancelled: &AtomicBool) -> Result { check_id: check.id.clone(), subject: plan.subject.clone(), invocation: check.invocation.clone(), - executable: check.invocation.program.clone(), - executable_sha256: None, + executable: resolved + .map(|path| path.to_string_lossy().into_owned()) + .unwrap_or_else(|| check.invocation.program.clone()), + executable_sha256, tool_version: None, started_at_ms: captured.started_at_ms, finished_at_ms: captured.finished_at_ms, @@ -818,12 +959,12 @@ fn load_receipts( Ok(receipts) } -fn evaluate_options(options: EvaluateOptions) -> Result { +fn evaluate_options(options: EvaluateOptions, cancelled: &AtomicBool) -> Result { let source_root = root(&options.root)?; let (_, plan) = read_plan(&options.plan)?; let paths: Vec<_> = plan.subject.inputs.iter().map(|a| a.path.clone()).collect(); let mut current = plan.subject.clone(); - current.revision = revision(&source_root)?; + current.revision = revision(&source_root, cancelled)?; current.inputs = inputs(&source_root, &paths, true)?; // An absent selected file is stale evidence, not a synthetic empty subject. if current.inputs.is_empty() { @@ -832,7 +973,7 @@ fn evaluate_options(options: EvaluateOptions) -> Result { "all selected source inputs are missing; evidence is stale", )); } - current.dirty = selected_dirty(&source_root, &paths)?; + current.dirty = selected_dirty(&source_root, &paths, cancelled)?; current.working_tree = if current.dirty { Some(Artifact { path: "current-selected-inputs.json".into(), @@ -885,9 +1026,9 @@ fn evaluate_options(options: EvaluateOptions) -> Result { &plan.subject.revision, ¤t.revision, ], + cancelled, )? - .status - .success() + .success { ancestors.push(plan.subject.revision.clone()); } @@ -956,7 +1097,7 @@ pub fn execute(cli: Cli, cancelled: &AtomicBool) -> Result { match cli.command { Operation::Plan { command: PlanCommand::Init(options), - } => init(options), + } => init(*options, cancelled), Operation::Plan { command: PlanCommand::Check { plan, json }, } => { @@ -981,7 +1122,7 @@ pub fn execute(cli: Cli, cancelled: &AtomicBool) -> Result { } | Operation::Expectations { command: ExpectationCommand::Check(options), - } => evaluate_options(options), + } => evaluate_options(options, cancelled), Operation::Deepsec(options) => { crate::deepsec::execute(&options, cancelled).map_err(|e| error(e.code, e.message)) } diff --git a/tests/native_cli.rs b/tests/native_cli.rs index 622519c..5a0f7a3 100644 --- a/tests/native_cli.rs +++ b/tests/native_cli.rs @@ -102,6 +102,12 @@ fn plan_run_and_evaluate_use_real_output_but_do_not_invent_scope_or_tests() { .unwrap(); assert_eq!(receipt.observed_scope, None); assert!(receipt.observed_tests.is_empty()); + let executable = Path::new("/bin/sh").canonicalize().unwrap(); + assert_eq!(receipt.executable, executable.to_str().unwrap()); + assert_eq!( + receipt.executable_sha256.as_deref(), + Some(visioncraft::sha256(&fs::read(executable).unwrap()).as_str()) + ); assert_eq!( fs::read(root.path().join("evidence/check-0000/stdout.log")).unwrap(), b"real-output" @@ -404,3 +410,210 @@ fn signal_termination_still_preserves_a_valid_nonpassing_receipt() { assert!(receipt.signal.is_some()); assert!(!evaluate(root.path()).status.success()); } + +#[test] +fn manual_context_and_explicit_current_subject_are_byte_checked() { + let root = fixture(); + init(root.path(), "printf ok"); + let plan_path = root.path().join("plan.json"); + let mut plan = QualityPlan::parse(&fs::read(&plan_path).unwrap()).unwrap(); + plan.expectations.push(visioncraft::Expectation { + id: "MANUAL-1".into(), + claim: "fixture observation".into(), + required: true, + category: visioncraft::EvidenceCategory::Manual, + checks: vec![], + regression_critical: false, + stabilizer: None, + positive_control: None, + independent_audit: false, + limitation: Some("synthetic manual-observation fixture".into()), + }); + fs::write(&plan_path, serde_json::to_vec(&plan).unwrap()).unwrap(); + success(&run(root.path())); + assert_eq!(evaluate(root.path()).status.code(), Some(1)); + let receipt = ExecutionReceipt::parse( + &fs::read(root.path().join("evidence/check-0000/receipt.json")).unwrap(), + ) + .unwrap(); + let record = b"fixture observer recorded the scoped state"; + fs::write(root.path().join("evidence/manual.txt"), record).unwrap(); + let observation = visioncraft::ManualObservation { + expectation_id: "MANUAL-1".into(), + plan_sha256: plan.digest().unwrap(), + subject: plan.subject.clone(), + observer: "fixture observer".into(), + observed: "scoped fixture state".into(), + verdict: visioncraft::AuditVerdict::Supported, + artifact: visioncraft::Artifact { + path: "manual.txt".into(), + sha256: visioncraft::sha256(record), + }, + captured_at_ms: receipt.finished_at_ms, + }; + fs::write( + root.path().join("evidence/context.json"), + serde_json::to_vec(&serde_json::json!({"manual_observations":[observation]})).unwrap(), + ) + .unwrap(); + fs::write( + root.path().join("current.json"), + serde_json::to_vec(&plan.subject).unwrap(), + ) + .unwrap(); + let args = [ + "evaluate", + "plan.json", + "--receipts", + "evidence", + "--context", + "evidence/context.json", + "--current-subject", + "current.json", + "--json", + ]; + success(&cli(root.path(), &args)); + fs::write(root.path().join("evidence/manual.txt"), b"changed").unwrap(); + assert!(!cli(root.path(), &args).status.success()); +} + +#[test] +fn ambient_git_environment_cannot_redirect_metadata_to_a_sibling_repo() { + let root = fixture(); + let foreign = fixture(); + fs::write(foreign.path().join("source.txt"), "foreign bytes\n").unwrap(); + git( + foreign.path(), + &[ + "-c", + "user.name=Fixture", + "-c", + "user.email=fixture@example.invalid", + "commit", + "-am", + "foreign", + ], + ); + let result = Command::new(env!("CARGO_BIN_EXE_visioncraft")) + .current_dir(root.path()) + .env("GIT_DIR", foreign.path().join(".git")) + .env("GIT_WORK_TREE", foreign.path()) + .args([ + "plan", + "init", + "--out", + "plan.json", + "--input", + "source.txt", + "--configuration", + "fixture", + "--", + "/bin/true", + ]) + .output() + .unwrap(); + success(&result); + let plan = QualityPlan::parse(&fs::read(root.path().join("plan.json")).unwrap()).unwrap(); + let expected = String::from_utf8(git(root.path(), &["rev-parse", "HEAD"]).stdout).unwrap(); + assert_eq!(plan.subject.revision, expected.trim()); + assert!(!plan.subject.dirty); +} + +#[test] +fn committed_blob_size_is_bounded_before_requesting_blob_contents() { + use std::os::unix::fs::PermissionsExt; + let root = fixture(); + let tools = tempfile::tempdir().unwrap(); + let actual_git = String::from_utf8( + Command::new("sh") + .args(["-c", "command -v git"]) + .output() + .unwrap() + .stdout, + ) + .unwrap(); + let script = format!( + "#!/bin/sh\ncase \"$*\" in\n *'cat-file -s'*) printf '1073741825\\n';;\n *'cat-file blob'*) touch SHOULD_NOT_READ_BLOB; exit 1;;\n *) exec '{}' \"$@\";;\nesac\n", + actual_git.trim() + ); + fs::write(tools.path().join("git"), script).unwrap(); + fs::set_permissions(tools.path().join("git"), fs::Permissions::from_mode(0o755)).unwrap(); + let path = format!( + "{}:{}", + tools.path().display(), + std::env::var("PATH").unwrap() + ); + let result = Command::new(env!("CARGO_BIN_EXE_visioncraft")) + .current_dir(root.path()) + .env("PATH", path) + .args([ + "plan", + "init", + "--out", + "plan.json", + "--input", + "source.txt", + "--configuration", + "fixture", + "--", + "/bin/true", + ]) + .output() + .unwrap(); + assert_eq!(result.status.code(), Some(2)); + assert!(!root.path().join("SHOULD_NOT_READ_BLOB").exists()); + assert!(!root.path().join("plan.json").exists()); +} + +#[test] +fn cancellation_reaches_bounded_metadata_inspection_before_any_check_runs() { + use std::os::unix::fs::PermissionsExt; + let root = fixture(); + let tools = tempfile::tempdir().unwrap(); + fs::write(tools.path().join("git"), "#!/bin/sh\nsleep 30\n").unwrap(); + fs::set_permissions(tools.path().join("git"), fs::Permissions::from_mode(0o755)).unwrap(); + let path = format!( + "{}:{}", + tools.path().display(), + std::env::var("PATH").unwrap() + ); + let mut child = Command::new(env!("CARGO_BIN_EXE_visioncraft")) + .current_dir(root.path()) + .env("PATH", path) + .args([ + "plan", + "init", + "--out", + "plan.json", + "--input", + "source.txt", + "--configuration", + "fixture", + "--", + "/bin/true", + ]) + .stdout(std::process::Stdio::null()) + .stderr(std::process::Stdio::null()) + .spawn() + .unwrap(); + std::thread::sleep(std::time::Duration::from_millis(200)); + nix::sys::signal::kill( + nix::unistd::Pid::from_raw(child.id() as i32), + nix::sys::signal::Signal::SIGTERM, + ) + .unwrap(); + let start = std::time::Instant::now(); + let status = loop { + if let Some(status) = child.try_wait().unwrap() { + break status; + } + if start.elapsed() > std::time::Duration::from_secs(3) { + let _ = child.kill(); + let _ = child.wait(); + panic!("metadata child did not respond to cancellation"); + } + std::thread::sleep(std::time::Duration::from_millis(20)); + }; + assert_eq!(status.code(), Some(130)); + assert!(!root.path().join("plan.json").exists()); +} From 512e5e9d5bf5756a302f2327bb9e206b90f53db2 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 3 Nov 2026 11:13:43 +0000 Subject: [PATCH 10/16] Bind upstream evidence, bound aggregate plans and document portable workflows --- .github/workflows/ci.yml | 30 ++++++ LICENSE-APACHE | 176 ++++++++++++++++++++++++++++++ LICENSE-MIT | 21 ++++ README.md | 227 ++++++++++++++++++++++++++++++++++++++- docs/EXPECTATIONS.md | 9 +- docs/ZEROSHOT-LESSONS.md | 78 ++++++++++++++ src/deepsec.rs | 40 +++++-- src/deepsec_evidence.rs | 23 ++-- src/lib.rs | 4 + src/plan.rs | 27 +++++ src/process.rs | 30 +++++- tests/core.rs | 38 +++++++ tests/deepsec.rs | 2 +- 13 files changed, 679 insertions(+), 26 deletions(-) create mode 100644 .github/workflows/ci.yml create mode 100644 LICENSE-APACHE create mode 100644 LICENSE-MIT create mode 100644 docs/ZEROSHOT-LESSONS.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..5d764e1 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,30 @@ +name: CI +on: + push: + branches: [main] + pull_request: +permissions: + contents: read +jobs: + quality: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 + - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable, inspected 2026-11-03 + with: + components: rustfmt,clippy + - run: cargo fmt --check + - run: cargo clippy --locked --all-targets -- -D warnings + - run: cargo test --locked + - run: cargo test --locked --no-default-features + - run: cargo doc --locked --no-deps + env: + RUSTDOCFLAGS: -D warnings + - run: cargo package --locked + msrv: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 + - uses: dtolnay/rust-toolchain@cfcaf53ba4c621917ec7f78a66bff7a8848ddad4 # 1.85.0 + - run: cargo check --locked --all-targets + - run: cargo check --locked --no-default-features diff --git a/LICENSE-APACHE b/LICENSE-APACHE new file mode 100644 index 0000000..1b5ec8b --- /dev/null +++ b/LICENSE-APACHE @@ -0,0 +1,176 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + +5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS diff --git a/LICENSE-MIT b/LICENSE-MIT new file mode 100644 index 0000000..747d4af --- /dev/null +++ b/LICENSE-MIT @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 DreamLab-AI and VisionCraft contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 8416559..c76cb61 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,226 @@ # VisionCraft -Portable engineering guidance and executable quality contracts. The development -contract is in [docs/EXPECTATIONS.md](docs/EXPECTATIONS.md). This repository is -under active implementation; no release has been published yet. +**Engineering guidance and executable evidence gates for coding agents and people.** + +VisionCraft helps you define a change, run proportionate checks, assess what the +results support, and carry that evidence through review and release. Use its +[skill](skills/visioncraft/SKILL.md), Rust library, CLI, or a combination. + +It works without Agentbox, an orchestration framework or a model subscription. +The library does not launch processes or make network calls. The optional CLI +runs explicitly requested commands; optional upstream tools provide their own +specialist capabilities. + +## What belongs where + +| Component | Responsibility | +|---|---| +| VisionCraft skill | EDD/TDD, debugging, design decisions, review and delivery practices | +| VisionCraft Rust core | Typed plans, evidence identity, expectation coverage and deterministic gate decisions | +| VisionCraft CLI | Explicit command execution, bounded private captures and filesystem verification | +| Agentic QE | Optional upstream QE tools: generate tests, inspect coverage and assess supplied quality evidence | +| Deepsec | Optional upstream security investigations through a versioned CLI adapter | +| Sealmap | Source-derived diagrams, model-family identity and adjacent finding-disposition contracts | +| Your repository and CI | Authoritative requirements, ADRs, tests, configuration and release observations | + +A passing gate means the declared checks and evidence policy were satisfied. +It is not proof of correctness, security, complete test coverage or deployment. + +## Install + +Rust 1.85 or later is required. The process CLI currently supports Unix. + +```sh +cargo install visioncraft --locked --version 0.1.0 +visioncraft --help +``` + +For the pure Rust library without CLI/process dependencies: + +```toml +[dependencies] +visioncraft = { version = "0.1.0", default-features = false } +``` + +For a coding agent, install the complete `skills/visioncraft/` directory from the +same release using your harness's skill mechanism. Keep its `references/` and +`assets/` alongside `SKILL.md`; they contain the actual engineering method. +Reading a skill does not install or start any upstream service. + +## A complete local example + +Create a small Git repository with a real assertion. The input list explicitly +includes the files whose bytes the check claims to cover. + +```sh +mkdir visioncraft-example +cd visioncraft-example +git init -q +printf '12\n' > limit.txt +git add limit.txt +git -c user.name=Example -c user.email=example@example.invalid commit -qm baseline + +visioncraft plan init --out quality.json --input limit.txt \ + --configuration 'POSIX assertion of configured limit' \ + -- sh -c 'test "$(cat limit.txt)" = 12' +visioncraft plan check quality.json --json +visioncraft run quality.json --all --out evidence-1 +visioncraft evaluate quality.json --receipts evidence-1 --json +``` + +The final command verifies the plan, exact source and capture hashes, check +invocation and recorded exit. `run` reports execution status; `evaluate` makes +the quality-gate decision. The explicit `sh -c` above asks for shell syntax; +VisionCraft itself passes argument arrays directly and adds no shell. + +Change `limit.txt` after running the check and repeat `evaluate`: the old +receipt cannot satisfy the new input. Create a new plan and fresh run directory +after intentionally changing a check's scope or configuration. Existing output +paths are refused to avoid overwriting evidence. + +For a real project, include relevant source, lockfiles and configuration in +`--input`; pass required environment **names** with repeated `--env` options. +Only named environment variables are inherited. Set useful `--timeout-ms` and +`--max-output-bytes` bounds rather than relying on unlimited jobs. A plan admits at most 1,024 checks, one +day of summed command deadlines and one GiB of summed capture limits. + +## Expectations and review + +The [EDD reference](skills/visioncraft/references/edd.md) describes executable, +partly verifiable and manual expectations. A plan can bind expectations to +checks, positive controls, stabilising regression tests and independent audit +requirements. Generic command execution cannot infer which test IDs or source +lines a test runner reached; observed coverage remains unknown unless an +observer supplies it. + +```sh +visioncraft expectations check quality.json --receipts evidence-1 --json +visioncraft gate evaluate quality.json --receipts evidence-1 --json +``` + +Both evaluate the entire required gate. Neither hides failed checks merely +because an expectation does not refer to them. Missing, skipped, timed-out, +stale and incomplete required evidence remains non-passing. Optional failures +remain visible without silently becoming required. + +For imported findings, use Sealmap's existing receipt contract: + +```sh +sealmap review init findings.json --out finding-receipts.json +# Add actual reproductions and dispositions, preserving the original findings. +sealmap review check finding-receipts.json --json +sealmap review summary finding-receipts.json +``` + +VisionCraft consumes Sealmap's contracts rather than maintaining another finding +validator. Schema checks and byte hashes establish evidence identity; an auditor +still has to judge whether the evidence supports the claim. + +## Specialist upstreams + +Deepsec is an independently installed optional reviewer. The adapter supports +the exact protocol recorded in [its release contract](contracts/deepsec.json). +No command implicitly installs it, logs in, changes model routes or starts a +review merely because you read the skill. + +```sh +# Inspect the resolved plan without running a reviewer. +visioncraft deepsec --diff origin/main --dry-run +# Run the explicitly requested review using already configured local credentials. +visioncraft deepsec --diff origin/main +# Candidate discovery only; SCANNED is not a completed review. +visioncraft deepsec --scan-only +``` + +The adapter freezes selected file names, checks their bytes before and after, +and requires fresh per-file analysis evidence. In staged mode, differing index +and working-tree bytes are refused. An empty export, refusal, partial review, +unknown completion or unsupported tool version cannot produce PASS. Full mode +reviews the scanner's pending candidates; it does not establish whole-program +coverage. Historical findings may remain in the exported threshold assessment. +Read [the integration guide](skills/visioncraft/references/deepsec.md) before +choosing source scope, model route or spend limits. The [upstream maintenance +procedure](docs/UPSTREAM-DEEPSEC.md) explains how to qualify a new release; +upstream `main`, a published package and an activated host are separate versions. + +Agentic QE is consumed through its own discovered CLI/MCP surface. Its +[worked integration](skills/visioncraft/references/agentic-qe.md) and +[versioned result contract](contracts/agentic-qe.json) define that boundary. Generated +tests must be inspected and executed in the project. Preserve measured versus +estimated coverage and `insufficient-evidence` outcomes; a recommendation or a +registered agent name is not an executed check. + +## Architecture records and diagrams + +Use the project's existing ADR and diagram corpus. Link requirements, decisions, +code, checks and release observations. Implemented claims carry an inspected +commit and nonempty governed paths. Updating a diagram's rendering does not +verify its source claims; a clean relationship graph does not make an ADR current. + +[Decision guidance](skills/visioncraft/references/methodologies.md), +[diagram diagnosis](skills/visioncraft/references/diagram-diagnosis.md) and +[traceability](skills/visioncraft/references/traceability.md) explain how to keep +these records useful without building a second documentation database. + +## Rust library + +The core accepts typed data and supplied bytes. It does not trust an artifact +because its filename or claimed hash looks plausible: + +```rust +use visioncraft::{Artifact, VerifiedArtifacts}; + +let bytes = b"actual check output\n"; +let artifact = Artifact { + path: "attempt/stdout.log".into(), + sha256: visioncraft::sha256(bytes), +}; +let mut verified = VerifiedArtifacts::default(); +verified.insert(&artifact, bytes)?; +assert!(verified.contains(&artifact)); +# Ok::<(), visioncraft::ContractError>(()) +``` + +`QualityPlan`, `ExecutionReceipt` and `EvaluationContext` describe the policy, +observations and verified current inputs. `evaluate` returns both the aggregate +outcome and individual check/expectation results. See the generated rustdoc and +[executable contract tests](tests/core.rs) for complete typed examples. + +## Place in the ecosystem: Agentbox + +Agentbox is one consumer. It installs a pinned VisionCraft release, distributes +that release's canonical skill, projects host policy and credentials, and +registers VisionCraft in its local and Jev-assisted skill picker. Ruflo supplies +coordination; direct Agentic QE tools supply QE capabilities. Neither is needed +for portable library use. + +Agentbox's Deepsec policy translator passes a typed configuration into the same +VisionCraft CLI used elsewhere. It does not retain a second gate implementation. +The hard cutover removes active `build-with-quality` entry points after checks +pass; [the migration guide](docs/MIGRATION.md) maps every former resource. +A committed pin is not evidence that an already running container adopted it. + +The [Agentbox integration reference](skills/visioncraft/references/ecosystem-agentbox.md) +is the expanding record of that deployment's memory, routing and operational +boundaries. Other hosts can supply their own adapters without importing them. + +## Limits and development + +The process runner is **not a sandbox**. Children retain the caller's filesystem +and network authority; environment filtering is not secret isolation. Unix +process groups support cancellation and deadlines, but a deliberately escaping +process or a blocked kernel filesystem call needs host-level containment. +Private capture directories protect ordinary local handling, not a hostile +concurrent filesystem. Keep source-bearing evidence out of public commits. + +Run `cargo test`, `cargo clippy --all-targets -- -D warnings`, `cargo fmt --check` +and `RUSTDOCFLAGS='-D warnings' cargo doc --no-deps`. The +[implementation contract](docs/EXPECTATIONS.md) records acceptance boundaries. +[Zeroshot lessons](docs/ZEROSHOT-LESSONS.md) document source-grounded design +patterns adopted without importing another execution engine. Structural skill +checks and forward evaluations are reported separately from +any measured improvement; this rewrite does not imply a success-rate uplift. + +MIT OR Apache-2.0. Attributed BeautifulRust material retains its original MIT +notice. See [provenance](docs/PROVENANCE.md), [MIT](LICENSE-MIT) and +[Apache-2.0](LICENSE-APACHE). diff --git a/docs/EXPECTATIONS.md b/docs/EXPECTATIONS.md index b33587a..f7330eb 100644 --- a/docs/EXPECTATIONS.md +++ b/docs/EXPECTATIONS.md @@ -13,14 +13,17 @@ and inventory retained in Agentbox docs/developer/visioncraft-handoff/. 3. Required missing/failed/skipped/unknown evidence never becomes PASS. Preserve actual errors and successful controls; schema, scope and bytes are explicit. 4. Commands run only through explicit run/security operations, as argv with a - deadline/output bounds, complete child cleanup and private evidence. Imported + deadline/output bounds, process-group cleanup and private evidence. Imported receipts, inspection and reports never execute their contents. 5. Consume Sealmap 0.4 for disposition and family contracts; delegate existing receipt byte checks to Sealmap. Preserve separate source/test/merge/publish/ adoption/deployment facts. A runner is not a sandbox. 6. Replace the actual Deepsec compatibility consumer and migrate Agentbox - registries, routes, resources and CI. Keep the legacy name/script paths as - thin adapters to one canonical payload. Generic use needs no Agentbox. + registries, routes, resources and CI. Once green, remove the old active skill + and implementation; the operator authorised a hard cutover and will rebuild. + Jev and both harness registries must select the canonical VisionCraft payload. + Generic use needs no Agentbox. Consume Agentic QE through its separate upstream + CLI/MCP surface, with versioned contracts and no copied QE engine. 7. Publish complete docs/licences/rustdoc/examples and execute offline regression controls, package checks, independent review and registry-consumer checks. Skill-builder compliance is distinct from measured skill-tuning results. diff --git a/docs/ZEROSHOT-LESSONS.md b/docs/ZEROSHOT-LESSONS.md new file mode 100644 index 0000000..ca031e6 --- /dev/null +++ b/docs/ZEROSHOT-LESSONS.md @@ -0,0 +1,78 @@ +# Lessons from Zeroshot + +Reviewed 3 November 2026 at +[`df16ca0cb5ceb5e2503a770f53b45578f4d8b731`](https://github.com/the-open-engine/zeroshot/tree/df16ca0cb5ceb5e2503a770f53b45578f4d8b731). +This is a source and contract review, not an executed qualification of Zeroshot. +No dependency or engine source was imported. + +## Admission before execution + +Zeroshot's production verifier checks structural validity and resource bounds +before looking up worker implementations. It derives aggregate bounds across +sequences, branches, maps and loops rather than trusting each worker's local +limit. The verifier distinguishes invalid inputs from internal faults. +[Source](https://github.com/the-open-engine/zeroshot/blob/df16ca0cb5ceb5e2503a770f53b45578f4d8b731/crates/openengine-cluster-server/src/graph_verifier.rs). + +Applied to VisionCraft's smaller contract: a plan admits at most 1,024 checks; +its declared deadlines sum to at most one day and capture limits to at most one +GiB, including optional checks. Checked arithmetic rejects overflow. The +regression combines individually valid checks whose aggregate exceeds the +ceiling, beside an exact-boundary passing control. This bounds one declared +pass, not arbitrary repeated invocations or blocked kernel I/O. VisionCraft has +no retry graph or implicit model worker fleet. + +## Review sessions and authority + +Zeroshot's software-change workflow retains the worker session for repairs and +starts reviewers afresh. Authored graph structure controls which reviews must +succeed and where rejection returns the work. +[Workflow](https://github.com/the-open-engine/zeroshot/blob/df16ca0cb5ceb5e2503a770f53b45578f4d8b731/README.md#save-and-reuse-a-profile). + +Useful host practice: scope each reviewer to the current candidate and evidence, +use a fresh reviewer context for a new repair pass, and keep the worker's own +account as a claim. Session separation does not establish model-family +independence. VisionCraft already checks the actual actor/family evidence when +that independence is required. A model response cannot reuse a receipt after +changing its bound plan or silently turn a missing required check into an +optional one. + +## Delivery is an observation of an external effect + +Zeroshot's inspected change separates a graph's output from delivery confirmed +by its runtime history, and retains a reference to that confirmation for replay. +The commit describes matching the delivery target and final writer and keeping +an unsuccessful graph unsuccessful despite a delivery receipt. +[Change](https://github.com/the-open-engine/zeroshot/commit/df16ca0cb5ceb5e2503a770f53b45578f4d8b731). + +This supports the existing VisionCraft/Sealmap separation between source, tests, +merge, publication, consumer adoption and live deployment. Keep each receipt +bound to the actual revision and target. A natural-language completion message, +passing quality gate or published crate must not substitute for a live runtime +observation. Use Sealmap's existing delivery axes instead of another status store. + +## Recovery and observation + +Zeroshot's recovery contract gives a successor a new run identity, restores a +specific source/input checkpoint and resolves credentials again. Parallel writer +groups share a group checkpoint. Its observer can detach without terminating +the controller; stopping the run is a separate operation. +[Contract](https://github.com/the-open-engine/zeroshot/blob/df16ca0cb5ceb5e2503a770f53b45578f4d8b731/docs/guides/observe-and-control.md). + +VisionCraft keeps every execution in a fresh directory and rejects stale or +mutated source/evidence. Host orchestration owns checkpoint recovery, including +writer quiescence and credential refresh. The foreground VisionCraft CLI owns +its child process group and cancels it on interruption; it is not a detached +controller. Host adapters must state which lifetime they control. + +## Optional future consumption + +Zeroshot publishes separate protocol, server, client and testkit crates in its +workspace; its graph verifier lives in the server crate with runtime dependencies. +[Manifest](https://github.com/the-open-engine/zeroshot/blob/df16ca0cb5ceb5e2503a770f53b45578f4d8b731/crates/openengine-cluster-server/Cargo.toml). + +A future orchestrator integration should consume a qualified upstream release +through an explicit host boundary. First compare it with the host's existing +Ruflo/session services, define one execution owner, qualify failure and recovery +behaviour, and pin the protocol. Its presence or an installed harness binary +alone does not establish an enabled adapter. VisionCraft's portable gate remains +usable without that runtime. diff --git a/src/deepsec.rs b/src/deepsec.rs index 0784181..e561eea 100644 --- a/src/deepsec.rs +++ b/src/deepsec.rs @@ -19,7 +19,15 @@ use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH}; #[path = "deepsec_evidence.rs"] mod recorded; -const VERSION: &str = "2.3.10"; +static PROTOCOL: std::sync::LazyLock = std::sync::LazyLock::new(|| { + serde_json::from_str(include_str!("../contracts/deepsec.json")) + .expect("checked-in Deepsec release contract must be valid JSON") +}); +fn supported_version() -> &'static str { + PROTOCOL["package"]["version"] + .as_str() + .expect("release contract version") +} const SEVERITIES: [&str; 6] = ["CRITICAL", "HIGH", "MEDIUM", "HIGH_BUG", "BUG", "LOW"]; static ATTEMPT: AtomicU64 = AtomicU64::new(0); @@ -237,7 +245,7 @@ pub struct DeepsecOptions { /// Read newline-delimited file paths, or `-` for stdin. #[arg(long)] pub files_from: Option, - /// Scan and process the entire repository. + /// Scan the repository and process its pending candidates. #[arg(long)] pub full: bool, /// Scan without model processing; result is SCANNED, not review PASS. @@ -680,7 +688,7 @@ pub fn execute(options: &DeepsecOptions, cancelled: &AtomicBool) -> Result Result = None; + let mut observed_version: Option = None; let outcome = (|| -> Result { let (rc, version) = attempt.command( "version", @@ -758,12 +767,19 @@ pub fn execute(options: &DeepsecOptions, cancelled: &AtomicBool) -> Result Result = expected + .iter() + .map(|artifact| { + ( + artifact.path.clone(), + file_record(data, &artifact.path).unwrap_or(Value::Null), + ) + }) + .collect(); + // Preserve rejected state as well as successful observations. The decoder's + // raw state remains private; a null entry means its file could not be read. + let evidence = json!({"runs":runs,"files":records}); + let bytes = serde_json::to_vec_pretty(&evidence) + .map_err(|_| error(70, "review evidence encoding failed"))?; + write_new(&report.join("review-evidence.json"), &bytes)?; if runs.len() != 1 { return Err(error(70, "missing or ambiguous fresh processing run")); } @@ -251,9 +266,8 @@ pub(super) fn validate_review( "processing run is incomplete or covers another scope", )); } - let mut records = BTreeMap::new(); for artifact in expected { - let record = file_record(data, &artifact.path)?; + let record = &records[&artifact.path]; if record["filePath"] != artifact.path || record["projectId"] != project || record["fileHash"] != artifact.sha256 @@ -296,12 +310,7 @@ pub(super) fn validate_review( "review lacks actual model identity or output evidence", )); } - records.insert(artifact.path.clone(), record); } - let evidence = json!({"run":run,"files":records}); - let bytes = serde_json::to_vec_pretty(&evidence) - .map_err(|_| error(70, "review evidence encoding failed"))?; - write_new(&report.join("review-evidence.json"), &bytes)?; Ok( json!({"run_id":run_id,"observed_files":expected.iter().map(|a|&a.path).collect::>(),"evidence_sha256":sha256(&bytes),"coverage_boundary":"Recorded per-file investigations of exact selected bytes; dependencies and runtime behaviour remain outside this observation."}), ) diff --git a/src/lib.rs b/src/lib.rs index 797b2f1..1d94a81 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -123,3 +123,7 @@ pub mod process; /// Versioned adapter for an independently installed Deepsec reviewer. #[cfg(feature = "cli")] pub mod deepsec; + +/// Explicit command-line and filesystem adapter for the quality core. +#[cfg(feature = "cli")] +pub mod cli; diff --git a/src/plan.rs b/src/plan.rs index 97ed084..82ad4ca 100644 --- a/src/plan.rs +++ b/src/plan.rs @@ -7,6 +7,13 @@ use crate::{ use serde::{Deserialize, Serialize}; use std::collections::BTreeSet; +/// Maximum number of declared checks, including optional checks, in one plan. +pub const MAX_PLAN_CHECKS: usize = 1024; +/// Maximum sum of declared command deadlines: one day, excluding bounded cleanup. +pub const MAX_PLAN_DURATION_MS: u64 = 86_400_000; +/// Maximum sum of declared stdout/stderr capture bounds: one GiB per plan. +pub const MAX_PLAN_OUTPUT_BYTES: u64 = 1_073_741_824; + /// Immutable code and configuration identity examined by a plan. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] @@ -287,6 +294,10 @@ impl QualityPlan { /// Returns the first contract violation, without reading external resources. pub fn validate(&self) -> Result<(), ContractError> { require(self.version == 1, "unsupported plan version")?; + require( + self.checks.len() <= MAX_PLAN_CHECKS, + "plan check count exceeds admission ceiling", + )?; require(identifier(&self.id), "invalid plan id")?; self.subject.validate()?; require( @@ -299,12 +310,28 @@ impl QualityPlan { )?; let inputs: BTreeSet<_> = self.subject.inputs.iter().map(|x| &x.path).collect(); let mut ids = BTreeSet::new(); + let mut duration = 0_u64; + let mut output_bytes = 0_u64; for c in &self.checks { require( identifier(&c.id) && ids.insert(&c.id), "invalid or duplicate check id", )?; c.invocation.validate()?; + duration = duration + .checked_add(c.invocation.timeout_ms) + .ok_or_else(|| ContractError::Invalid("aggregate deadline overflow".into()))?; + output_bytes = output_bytes + .checked_add(c.invocation.max_output_bytes) + .ok_or_else(|| ContractError::Invalid("aggregate capture overflow".into()))?; + require( + duration <= MAX_PLAN_DURATION_MS, + "aggregate declared deadlines exceed one day", + )?; + require( + output_bytes <= MAX_PLAN_OUTPUT_BYTES, + "aggregate declared captures exceed one GiB", + )?; require(!c.scope.is_empty(), "check scope cannot be empty")?; let mut scope = BTreeSet::new(); for p in &c.scope { diff --git a/src/process.rs b/src/process.rs index 15bf144..2139bc7 100644 --- a/src/process.rs +++ b/src/process.rs @@ -209,10 +209,37 @@ pub fn run_command( output: &Path, cancelled: &AtomicBool, inherit_stdin: bool, +) -> io::Result { + run_command_with_env( + invocation, + root, + output, + cancelled, + inherit_stdin, + &std::collections::BTreeMap::new(), + ) +} + +// Internal fixed-value metadata policy only. User checks declare inherited +// names in Invocation; their values are deliberately absent from receipts. +pub(crate) fn run_command_with_env( + invocation: &Invocation, + root: &Path, + output: &Path, + cancelled: &AtomicBool, + inherit_stdin: bool, + overrides: &std::collections::BTreeMap, ) -> io::Result { #[cfg(not(unix))] { - let _ = (invocation, root, output, cancelled, inherit_stdin); + let _ = ( + invocation, + root, + output, + cancelled, + inherit_stdin, + overrides, + ); Err(io::Error::new( io::ErrorKind::Unsupported, "bounded process groups require Unix", @@ -273,6 +300,7 @@ pub fn run_command( command.env(name, value); } } + command.envs(overrides); let mut child = match command.spawn() { Ok(child) => child, Err(err) => { diff --git a/tests/core.rs b/tests/core.rs index eba222d..2593786 100644 --- a/tests/core.rs +++ b/tests/core.rs @@ -632,3 +632,41 @@ fn a_supplied_contradiction_cannot_be_ignored_as_unrequested_optional_metadata() context.audits = &audits; assert!(!evaluate(&plan, &runs, &context).passed()); } + +#[test] +fn valid_individual_checks_cannot_form_an_unbounded_aggregate_plan() { + let mut p = plan(); + p.checks.truncate(2); + for check in &mut p.checks { + check.invocation.timeout_ms = 43_200_000; + check.invocation.max_output_bytes = 536_870_912; + } + assert!( + p.validate().is_ok(), + "exact aggregate ceilings remain usable" + ); + p.checks[1].invocation.timeout_ms += 1; + assert!( + p.validate().is_err(), + "individually valid deadlines cannot exceed the whole-plan ceiling" + ); + p.checks[1].invocation.timeout_ms -= 1; + p.checks[1].invocation.max_output_bytes += 1; + assert!( + p.validate().is_err(), + "individually valid captures cannot exceed the aggregate ceiling" + ); + let mut p = plan(); + let seed = p.checks[0].clone(); + p.checks = (0..1025) + .map(|n| { + let mut c = seed.clone(); + c.id = format!("check-{n}"); + c + }) + .collect(); + assert!( + p.validate().is_err(), + "required and optional checks share admission limits" + ); +} diff --git a/tests/deepsec.rs b/tests/deepsec.rs index 4a3b88b..ffce1ba 100644 --- a/tests/deepsec.rs +++ b/tests/deepsec.rs @@ -2,7 +2,7 @@ #![cfg(all(unix, feature = "cli"))] use serde_json::{Value, json}; use std::fs; -use std::path::{Path, PathBuf}; +use std::path::PathBuf; use std::process::{Command, Output}; struct Fixture { _temp: tempfile::TempDir, From a218a294a761aea01c510fbeb848e8b43efc02a2 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 3 Nov 2026 11:15:10 +0000 Subject: [PATCH 11/16] docs: retain verified local README example and stale-input control --- docs/README-EXAMPLE.md | 48 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 docs/README-EXAMPLE.md diff --git a/docs/README-EXAMPLE.md b/docs/README-EXAMPLE.md new file mode 100644 index 0000000..d5f8927 --- /dev/null +++ b/docs/README-EXAMPLE.md @@ -0,0 +1,48 @@ +# README example verification + +[README.md](../README.md#a-complete-local-example)'s local assertion example +was executed on 2026-11-03 in a fresh owned Git repository, using a copied local +debug binary reporting `visioncraft 0.1.0`. This verifies the local command path; +it is not evidence of package publication, consumer adoption or deployment. + +Inspected README SHA-256: +`c7c6114d798b70766da974ed31d79d67585ba681108a60d58598792e085c40d8`. +Executed binary SHA-256: +`ba494a4047713f94b6db4fff5d6fff8ad874c748463c30ce7e9ef11e4a9d8196`. + +After creating and committing `limit.txt` containing `12`, these commands ran: + +```sh +visioncraft plan init --out quality.json --input limit.txt \ + --configuration 'POSIX assertion of configured limit' \ + -- sh -c 'test "$(cat limit.txt)" = 12' +visioncraft plan check quality.json --json +visioncraft run quality.json --all --out evidence-1 +visioncraft evaluate quality.json --receipts evidence-1 --json +visioncraft expectations check quality.json --receipts evidence-1 --json +visioncraft gate evaluate quality.json --receipts evidence-1 --json +``` + +All six commands returned exit 0. Evaluation reported `passed`, with one required +check and one passed check. The fixture defines no separate expectations; those +empty expectations are not additional evidence of behaviour. + +Changing the selected input without rerunning its check exercised stale evidence: + +```sh +printf '13\n' > limit.txt +visioncraft evaluate quality.json --receipts evidence-1 --json +``` + +Evaluation returned exit 1 with aggregate `incomplete`, the check `inconclusive`, +and reason `selected source inputs changed since review`. The old successful +receipt did not satisfy the modified input. This is a source-identity control, +not a claim that the changed assertion was executed and failed. + +Retained evidence includes exact argv, stdout/stderr, exit statuses, hashes, +the isolated fixture and the copied binary. No Cargo build, model call, Deepsec +review, AQE task or library documentation example ran in this verification. + +A separate local-link check inspected 50 Markdown files and 105 local file +links in the current repository, with zero missing targets. External URL +availability and heading-anchor correctness were outside that check. From 02a511299a24dde3058376e3ebe45501e8a032d5 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 3 Nov 2026 11:19:20 +0000 Subject: [PATCH 12/16] Record source-verified architecture decisions and generated Sealmap corpus --- README.md | 3 +- docs/adr/0001-portable-quality-contract.md | 63 ++ .../0002-specialist-upstream-boundaries.md | 61 ++ docs/diagrams/README.md | 49 ++ docs/diagrams/generated/_README.md | 58 ++ docs/diagrams/generated/_index.json | 1 + docs/diagrams/generated/_overview.md | 365 +++++++++++ docs/diagrams/generated/src/cli.rs.md | 565 ++++++++++++++++++ docs/diagrams/generated/src/deepsec.rs.md | 376 ++++++++++++ .../generated/src/deepsec_evidence.rs.md | 234 ++++++++ docs/diagrams/generated/src/evaluate.rs.md | 234 ++++++++ docs/diagrams/generated/src/evidence.rs.md | 194 ++++++ docs/diagrams/generated/src/lib.rs.md | 45 ++ docs/diagrams/generated/src/main.rs.md | 20 + docs/diagrams/generated/src/plan.rs.md | 212 +++++++ docs/diagrams/generated/src/process.rs.md | 87 +++ 16 files changed, 2566 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0001-portable-quality-contract.md create mode 100644 docs/adr/0002-specialist-upstream-boundaries.md create mode 100644 docs/diagrams/README.md create mode 100644 docs/diagrams/generated/_README.md create mode 100644 docs/diagrams/generated/_index.json create mode 100644 docs/diagrams/generated/_overview.md create mode 100644 docs/diagrams/generated/src/cli.rs.md create mode 100644 docs/diagrams/generated/src/deepsec.rs.md create mode 100644 docs/diagrams/generated/src/deepsec_evidence.rs.md create mode 100644 docs/diagrams/generated/src/evaluate.rs.md create mode 100644 docs/diagrams/generated/src/evidence.rs.md create mode 100644 docs/diagrams/generated/src/lib.rs.md create mode 100644 docs/diagrams/generated/src/main.rs.md create mode 100644 docs/diagrams/generated/src/plan.rs.md create mode 100644 docs/diagrams/generated/src/process.rs.md diff --git a/README.md b/README.md index c76cb61..4920b41 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ results support, and carry that evidence through review and release. Use its [skill](skills/visioncraft/SKILL.md), Rust library, CLI, or a combination. It works without Agentbox, an orchestration framework or a model subscription. -The library does not launch processes or make network calls. The optional CLI +The deterministic core does not launch processes or make network calls. The optional CLI runs explicitly requested commands; optional upstream tools provide their own specialist capabilities. @@ -161,6 +161,7 @@ verify its source claims; a clean relationship graph does not make an ADR curren [diagram diagnosis](skills/visioncraft/references/diagram-diagnosis.md) and [traceability](skills/visioncraft/references/traceability.md) explain how to keep these records useful without building a second documentation database. +This project dogfoods that workflow in its [verified ADRs and diagrams](docs/diagrams/README.md). ## Rust library diff --git a/docs/adr/0001-portable-quality-contract.md b/docs/adr/0001-portable-quality-contract.md new file mode 100644 index 0000000..2a31a84 --- /dev/null +++ b/docs/adr/0001-portable-quality-contract.md @@ -0,0 +1,63 @@ +--- +id: ADR-0001 +title: Portable quality contracts with explicit execution adapters +status: accepted +date: 2026-11-03 +verified_commit: 6f233886824ef3896cbd8c18fd35fc3b9fbc2bb6 +verified_paths: + - src/plan.rs + - src/evidence.rs + - src/evaluate.rs + - src/cli.rs + - src/process.rs + - Cargo.toml +--- + +# Portable quality contracts with explicit execution adapters + +## Context + +The original engineering skill mixed useful methods, host-specific orchestration, +an executable security wrapper and stale descriptions of retired implementations. +Extraction needs a useful reusable library and one canonical skill, while retaining +the host's authority over credentials, tools and deployment. + +## Decision + +The deterministic core accepts plans, receipts, verified artifact bytes and an +injected evaluation context. It performs no filesystem or network operations. +Plans bind code/configuration and literal invocations; aggregate admission bounds +are checked before execution. Required missing, incomplete or contradicted evidence +cannot become a pass by omission. Observed coverage is distinct from intended scope. + +Optional Unix process/CLI adapters execute explicit commands with private captures, +deadlines and process-group cancellation. Read-only evaluation never executes an +imported receipt's command. Fixed Git metadata probes use the same bounded runner, +remove ambient Git redirection and avoid repository clean filters. This is not an +operating-system sandbox. + +Sealmap owns model-family and finding-disposition contracts. VisionCraft reuses +those types and validates supplied execution evidence rather than introducing a +parallel finding store. Project ADRs and diagrams remain source-controlled records; +optional search/index tools are consumers. + +## Alternatives and consequences + +A prose-only extraction would preserve the original gap between requested checks +and executable evidence. A new agent orchestration runtime would duplicate host +execution and custody services. The selected boundary supports a pure library, +portable foreground CLI and independently maintained host adapters. + +Generic command receipts cannot prove test coverage or claim that a model inspected +all relevant code. Independent audits and manual observations remain explicit, +scoped evidence. Publication, adoption and live deployment require separate proof. + +## Verification + +`tests/core.rs` checks policy/input identity, aggregate limits, missing/partial +observations, counterexamples, controls and model-family independence. +`tests/native_cli.rs` checks actual execution, source drift, private snapshots, +read-only evaluation and confined metadata inspection. `tests/process.rs` exercises +literal arguments, environment selection, timeout/cancellation and capture failure. +The inspected implementation revision above predates this documentation commit; +refresh only after rechecking changes to its governed paths. diff --git a/docs/adr/0002-specialist-upstream-boundaries.md b/docs/adr/0002-specialist-upstream-boundaries.md new file mode 100644 index 0000000..da1feb4 --- /dev/null +++ b/docs/adr/0002-specialist-upstream-boundaries.md @@ -0,0 +1,61 @@ +--- +id: ADR-0002 +title: Consume specialist reviewers through versioned upstream contracts +status: accepted +date: 2026-11-03 +depends_on: [ADR-0001] +verified_commit: 6f233886824ef3896cbd8c18fd35fc3b9fbc2bb6 +verified_paths: + - src/deepsec.rs + - src/deepsec_evidence.rs + - contracts/deepsec.json + - contracts/agentic-qe.json + - skills/visioncraft/references/agentic-qe.md +--- + +# Consume specialist reviewers through versioned upstream contracts + +## Decision + +Deepsec and Agentic QE remain separate upstream implementations. The host installs +qualified versions and supplies credentials, source-sharing policy and spend +controls. VisionCraft consumes their observations with explicit provenance; neither +is a mandatory dependency of its deterministic library. + +Deepsec uses one native VisionCraft CLI adapter. It freezes source selection, +retains exact bytes' hashes, checks a fresh completed processing run and per-file +analysis records, rejects refusal/partial/unknown output, and applies the configured +severity threshold to the raw export. The receipt distinguishes observed CLI +version from expected package integrity and source revision. Installation integrity +belongs to host evidence. Full mode covers pending scanner candidates, not every +possible programme behaviour. + +AQE uses its own discovered MCP/CLI interfaces. Preserve measured, estimated and +insufficient-evidence outcomes. Execute generated tests with the project's real +runner. The versioned AQE result subsets describe observations and do not themselves +grant a successful quality gate. No second QE executor is introduced. + +## Host integration + +Agentbox supplies the concrete case: pinned release binary and canonical skill, +direct AQE MCP registration, a thin Deepsec policy translator, shared memory and +Jev-assisted discovery. It removes the old active build-with-quality implementation +when the replacement is qualified. A source pin is not runtime activation evidence; +the operator performs the subsequent image rebuild. + +AQE's ephemeral memory mode does not disable every embedding attempt. Its upstream +default embedding model differs from Agentbox's bge model. The integration does not +pretend that setting an endpoint alone establishes compatible semantic learning. + +## Maintenance and evidence + +[Deepsec maintenance](../UPSTREAM-DEEPSEC.md) names source/registry checks, protocol +fixtures, bounded smoke tests and coordinated host activation. The +[AQE guide](../../skills/visioncraft/references/agentic-qe.md) documents its direct +workflow and capability boundaries. Exact package/source metadata lives in the +contracts linked above, rather than competing defaults in each host. + +`tests/deepsec.rs` contains positive and negative protocol controls. Host fixtures +exercise policy precedence and disabled/unavailable paths through the actual +translator. A scan-only smoke test is recorded as SCANNED, never a completed model +review. Independent model review and package adoption have separate receipts. diff --git a/docs/diagrams/README.md b/docs/diagrams/README.md new file mode 100644 index 0000000..e6b2bab --- /dev/null +++ b/docs/diagrams/README.md @@ -0,0 +1,49 @@ +# VisionCraft diagrams and verification + +The [generated overview](generated/_overview.md) and +[per-source index](generated/_index.json) are extracted by Sealmap 0.4.0. Each +source document has source hashes, symbol identities, spans and call confidence. +Generated views are read-only; edit code and regenerate rather than hand-editing +the output. + +```sh +sealmap generate . --name visioncraft --public-only --min-calls 4 --no-model \ + --out docs/diagrams/generated +sealmap generate . --name visioncraft --public-only --min-calls 4 --no-model \ + --out docs/diagrams/generated --check +``` + +[ADR-0001](../adr/0001-portable-quality-contract.md) records the core/execution +boundary. [ADR-0002](../adr/0002-specialist-upstream-boundaries.md) records upstream +consumption. Source extraction, Mermaid rendering and runtime verification are +separate observations. + +The following authored view is verified against source at +`6f233886824ef3896cbd8c18fd35fc3b9fbc2bb6`: `src/cli.rs:1096`, +`src/plan.rs:295`, `src/evaluate.rs:532`, `src/process.rs:206`, +`src/deepsec.rs:576` and `src/deepsec_evidence.rs:220`. + +```mermaid +flowchart TD + User[Explicit CLI operation] --> Plan[Typed quality plan] + Plan --> Admit[Validate references and aggregate limits] + Admit --> Run[Run selected checks] + Run --> Process[Bounded Unix process group] + Process --> Receipt[Private execution receipts and raw captures] + Receipt --> Verify[Verify artifact bytes and current source] + Verify --> Gate[Evaluate checks and expectations] + Gate --> Result[Passed, blocked, incomplete or error] + User --> Security[Deepsec adapter] + Security --> External[Separately installed Deepsec] + External --> Observations[Run and per-file observations] + Observations --> SecurityGate[Check completion, source and threshold] + Skill[Portable engineering skill] --> AQE[Optional direct Agentic QE tools] + Skill --> ADR[Project ADRs and diagrams] + Skill --> Findings[Sealmap finding receipts] +``` + +The source-derived overview currently classifies the `recorded` alias, declared +with a Rust `path` attribute in `deepsec.rs`, as an external-looking call target. +It is the local `deepsec_evidence.rs` module, not a Cargo dependency. This known +extraction limit is recorded here instead of repairing generated output by hand. +Neither inferred edges nor diagram layout establish that a runtime followed a path. diff --git a/docs/diagrams/generated/_README.md b/docs/diagrams/generated/_README.md new file mode 100644 index 0000000..d5056a7 --- /dev/null +++ b/docs/diagrams/generated/_README.md @@ -0,0 +1,58 @@ +# sealmap corpus + +Generated by sealmap. Do not edit: `sealmap generate --check` reports any hand edit, and the next `sealmap generate` overwrites it. + +## Layout + +- `.md`: exactly one document per source file (the 1:1 contract). +- `_index.json`: every document and fragment, with participants, calls and merge links. +- `_model.json`: the full code model (symbols, spans, signatures, docs, relations). +- `_overview.md`: crate graph, module graphs, data models and trait maps. + +## Documents + +YAML front matter: `source`, `module`, `language`, `source_hash` (BLAKE3 of the +newline-normalised source), `lines`, `fragments`. + +Sections: + +- `## structure`: `classDiagram` of what the file defines. `<>` boxes + hold free functions, constants and submodules. Stubs annotated + `<>` are defined in another file; `<>` ones are outside + the codebase. Edges: `..|>` implements, `<|--` extends, `*--` owns, + `o--` holds via Option/Arc/Rc/&/collection, `..>` uses in a signature. +- ``## `sym:cargo crate . path/Type#fn().` ``: `sequenceDiagram` of one function's calls in source + order. The first lane is the function's owner (its type, or its module). + `alt`/`else` = if/match arms, `opt` = if-without-else, `if let` or closure, + `loop` = for/while/loop or per-element closure, `par` = spawned task. + A `~` prefix means the callee was inferred rather than proven. `?` suffix = + error propagates, `.await` = awaited. `Note` = early return. Lanes marked + `ext` are external crates. + +## Ids + +Every symbol is named by a `sym:` id with no file path, so moving code +between files keeps it: `sym:cargo . /#().`. +The suffix gives the kind: `/` module, `#` type or trait, `().` function or +method, `.` const or static, `!` macro; `[Trait]` marks a trait-impl +method (`Db#[Store]put().`). `sym:extern a::b` is a path outside the code +whose kinds are unknown; `sym:? name` is a method on a receiver of unknown +type. Names outside `[A-Za-z0-9_+$-]` are quoted in backticks. + +Every diagram id is derived from the `sym:` id by an injective encoding: +`__` before a module, `___t` before a type, `___f` before a function, and +so on (`my_crate__net___tClient___fconnect`). The same symbol has the same +diagram id everywhere, and no two symbols share one, so fragments can be +merged by id. + +In `_model.json` every symbol also carries `sig_hash` (its contract) and +`body_hash` (its implementation); comments, formatting and moves change +neither. + +## Merging + +In `_index.json`, each sequence fragment lists its `calls`. A call with +`expands: ""` points at the callee's own sequence fragment: +inline it to deepen a sequence, or follow it to stitch flows across files. +`confidence` is `exact` (resolved through paths, imports or declared types), +`inferred` (heuristic), or `external` (outside the codebase). diff --git a/docs/diagrams/generated/_index.json b/docs/diagrams/generated/_index.json new file mode 100644 index 0000000..e533d08 --- /dev/null +++ b/docs/diagrams/generated/_index.json @@ -0,0 +1 @@ +{"schema_version":2,"generator":"sealmap-corpus 0.4.0","codebase":"visioncraft","stats":{"files":9,"symbols":151,"relations":572,"flows":69,"calls":492},"documents":[{"source":"src/cli.rs","document":"src/cli.rs.md","module":"sym:cargo visioncraft . cli/","source_hash":"blake3:e883c6b79fba490bdf06476058ca4078ae6ce7a147e4308b65afd6c1326bdb7d","document_hash":"blake3:2220d5663cc889f21a54f8c8a819780e390a596c34834a2d205ba1879dacf41d","fragments":[{"id":"structure:src/cli.rs","kind":"structure","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/","span":{"start_line":1,"start_col":1,"end_line":1130,"end_col":1},"sig_hash":"blake3-16:a91e60562b65dab9be5fcfdd480a0025","body_hash":"blake3-16:40b5981fc262f7a390bc06718d7992c7","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft . cli/Cli#","sym:cargo visioncraft . cli/CliError#","sym:cargo visioncraft . cli/ContextFile#","sym:cargo visioncraft . cli/EvaluateOptions#","sym:cargo visioncraft . cli/ExpectationCommand#","sym:cargo visioncraft . cli/FamilyDeclaration#","sym:cargo visioncraft . cli/GateCommand#","sym:cargo visioncraft . cli/GitOutput#","sym:cargo visioncraft . cli/InitOptions#","sym:cargo visioncraft . cli/Operation#","sym:cargo visioncraft . cli/PlanCommand#","sym:cargo visioncraft . cli/RunOptions#","sym:cargo visioncraft . cli/SnapshotInput#"],"hash":"blake3:cc028d12f950c3ae1e85c12d11800b79b52157876e4bc9dd1614e6a982724168"},{"id":"sym:cargo visioncraft . cli/confined().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/confined().","span":{"start_line":218,"start_col":1,"end_line":244,"end_col":2},"sig_hash":"blake3-16:0f062b609af0623484ee4a8f3ce0791c","body_hash":"blake3-16:4d6d3d8c0f03abdfbfa2e19fad43f067","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":222},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":223},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":228},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":233},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":241}],"hash":"blake3:10134bbd7624f9bdd4c0c962084ddf99406fd07aaff1c112d8e6fde98e6256d2"},{"id":"sym:cargo visioncraft . cli/read_explicit().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/read_explicit().","span":{"start_line":266,"start_col":1,"end_line":278,"end_col":2},"sig_hash":"blake3-16:0135480ca8cad65a15367671ed65406d","body_hash":"blake3-16:2795f0c0dbe9df2e76d5b564e531760e","participants":["sym:cargo visioncraft . cli/"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":267},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":275},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":276,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":277}],"hash":"blake3:ea44521ca2c9580a30bcd4324260bf263e6d214f80c0579223fe16ef7cab9f86"},{"id":"sym:cargo visioncraft . cli/output_path().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/output_path().","span":{"start_line":280,"start_col":1,"end_line":305,"end_col":2},"sig_hash":"blake3-16:dbdb74d9394b0d29e9e3e8e51c008181","body_hash":"blake3-16:ca6d64c44631f2c0ee6c2ac804186a41","participants":["sym:cargo visioncraft . cli/"],"calls":[{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":289},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":295},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":297},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":299},{"target":"sym:cargo visioncraft . cli/io_error().","confidence":"exact","line":301}],"hash":"blake3:16ae04e0f4143479ef97deccd15f1e0d6c9c12d1f16c3de82ed63430b15466ec"},{"id":"sym:cargo visioncraft . cli/write_new().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/write_new().","span":{"start_line":307,"start_col":1,"end_line":319,"end_col":2},"sig_hash":"blake3-16:2d4d3f36490d72b3f6dc2d027eca4f3e","body_hash":"blake3-16:697a3ac4de3c725a30cfdc25488b8f86","participants":["sym:cargo visioncraft . cli/","sym:extern tempfile"],"calls":[{"target":"sym:cargo visioncraft . cli/output_path().","confidence":"exact","line":308,"expands":"sym:cargo visioncraft . cli/output_path()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":311},{"target":"sym:extern tempfile::NamedTempFile::new_in","confidence":"external","line":312},{"target":"sym:cargo visioncraft . cli/io_error().","confidence":"exact","line":317}],"hash":"blake3:457d2ebe0c5c2371326d12fd034f42e6ec1b554309aa824f919c052357d114df"},{"id":"sym:cargo visioncraft . cli/git().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/git().","span":{"start_line":338,"start_col":1,"end_line":418,"end_col":2},"sig_hash":"blake3-16:4841aa17643eae3fb5fe09d3badd3661","body_hash":"blake3-16:8785ef8586f97909ef447f795faf923b","participants":["sym:cargo visioncraft . cli/","sym:extern tempfile","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:extern tempfile::Builder::new","confidence":"external","line":339},{"target":"sym:extern tempfile::Builder::prefix","confidence":"external","line":340},{"target":"sym:extern tempfile::Builder::permissions","confidence":"external","line":344},{"target":"sym:extern tempfile::Builder::tempdir","confidence":"external","line":346},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":367},{"target":"sym:cargo visioncraft . process/run_command_with_env().","confidence":"exact","line":396,"expands":"sym:cargo visioncraft . process/run_command_with_env()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":408},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":410},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":411},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":412},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":413}],"hash":"blake3:430d4a769fcdfe36e5428007d37c2d7f77410f3778f3213d86dd937208bcfb58"},{"id":"sym:cargo visioncraft . cli/revision().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/revision().","span":{"start_line":420,"start_col":1,"end_line":430,"end_col":2},"sig_hash":"blake3-16:0b6fb7f218212ea850ac236d821d8a54","body_hash":"blake3-16:57f70fb943003d553d789a8ac8afdf57","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":421,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":423},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":426},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":427}],"hash":"blake3:6a47990d6e52a53cd8a184d578ac35266d83543a99f35ac8eb40a6ae358444e3"},{"id":"sym:cargo visioncraft . cli/selected_dirty().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/selected_dirty().","span":{"start_line":432,"start_col":1,"end_line":497,"end_col":2},"sig_hash":"blake3-16:466ae4a23ec9651aa81d4bed047fce21","body_hash":"blake3-16:60c71d02d369ba96d0e8ac250beb706a","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":437,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":439},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":450},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":452},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":458},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":465},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":466},{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":468,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":470},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":473},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":477},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":479},{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":481,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":483},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":485},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":487,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":488},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":492}],"hash":"blake3:453ed573926bd3366697d5f770d078d6675b2d10fc95e5d42b91b2998b8b86df"},{"id":"sym:cargo visioncraft . cli/inputs().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/inputs().","span":{"start_line":506,"start_col":1,"end_line":534,"end_col":2},"sig_hash":"blake3-16:ed0d5f7af2c90806f98bbe55046295b0","body_hash":"blake3-16:a4fe913978641a3fc470a6673895dbdd","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":509,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":512},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":512},{"target":"sym:cargo visioncraft . cli/io_error().","confidence":"exact","line":522},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":524}],"hash":"blake3:3f2dccdf84b13932d2d5f50d867c14fdcb3bccb66ede478c1abcba1fd56cc8a7"},{"id":"sym:cargo visioncraft . cli/source_snapshot().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/source_snapshot().","span":{"start_line":536,"start_col":1,"end_line":570,"end_col":2},"sig_hash":"blake3-16:99ceb13e4265b3151783ffc6a3e45c52","body_hash":"blake3-16:cbf9aee3425988e9536de14608e8da81","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:extern sealmap_corpus"],"calls":[{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":545,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":545},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":548},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":553},{"target":"sym:extern sealmap_corpus::review::Artifact::iter","confidence":"external","line":555},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":558},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":569}],"hash":"blake3:f3d87fe2bf48f895fb27ad21313f2b1c7930ba3db6156c76295df6bb381ab3a4"},{"id":"sym:cargo visioncraft . cli/init().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/init().","span":{"start_line":577,"start_col":1,"end_line":665,"end_col":2},"sig_hash":"blake3-16:b4e883cfce087fb3dfc81327eb4ad912","body_hash":"blake3-16:b5e11d29744c7e97abe293abd262f6ed","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":578},{"target":"sym:cargo visioncraft . cli/output_path().","confidence":"exact","line":579,"expands":"sym:cargo visioncraft . cli/output_path()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":583},{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":586},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":587},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":590,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":591,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/selected_dirty().","confidence":"exact","line":592,"expands":"sym:cargo visioncraft . cli/selected_dirty()."},{"target":"sym:cargo visioncraft . cli/source_snapshot().","confidence":"exact","line":594,"expands":"sym:cargo visioncraft . cli/source_snapshot()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":602},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":607},{"target":"sym:cargo visioncraft . plan/QualityPlan#validate().","confidence":"exact","line":647,"expands":"sym:cargo visioncraft . plan/QualityPlan#validate()."},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":648,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":649,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":650},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":653},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":655},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":656,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":658,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":660},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":660,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":661}],"hash":"blake3:2bd9ae15fbaff3cd2eec8f3f3539d22c3dd9870def20c2e0f278d9303ee76f01"},{"id":"sym:cargo visioncraft . cli/add_artifact().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/add_artifact().","span":{"start_line":667,"start_col":1,"end_line":675,"end_col":2},"sig_hash":"blake3-16:f0e71327596608de7e6b1f6a54853e2d","body_hash":"blake3-16:9b18aea04b32a8ac770134c2c7b25309","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . evidence/VerifiedArtifacts#"],"calls":[{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":672},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":673,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":673},{"target":"sym:cargo visioncraft . evidence/VerifiedArtifacts#insert().","confidence":"exact","line":674}],"hash":"blake3:9ab7e24505a5f71cd2e61508e0fabb0e233106589d756559b7851f0b72d83d88"},{"id":"sym:cargo visioncraft . cli/evidence_parent().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/evidence_parent().","span":{"start_line":687,"start_col":1,"end_line":698,"end_col":2},"sig_hash":"blake3-16:db2e97ad57784510b3ed00e2d46b651b","body_hash":"blake3-16:fb22ab4b05dcead0e83f694da33d202f","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":688},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":689},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":694},{"target":"sym:cargo visioncraft . cli/output_path().","confidence":"exact","line":697,"expands":"sym:cargo visioncraft . cli/output_path()."}],"hash":"blake3:937c15cb58ce91ca5a1f5e89aa9fcb15fec58a6dc29926f3858b097b62d99e3c"},{"id":"sym:cargo visioncraft . cli/run().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/run().","span":{"start_line":772,"start_col":1,"end_line":928,"end_col":2},"sig_hash":"blake3-16:ba17c27738cfde5ad2571ad58ca94d50","body_hash":"blake3-16:08da835ef954e7dd9cc676a5efc8ef47","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . process/","sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft . evidence/ExecutionReceipt#"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":773},{"target":"sym:cargo visioncraft . cli/read_plan().","confidence":"exact","line":774},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":781},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":785},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":790,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":793,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":794,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":796},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":803,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":803},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":804},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":805},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":809},{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":810},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":811,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":812},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":812,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/evidence_parent().","confidence":"exact","line":814,"expands":"sym:cargo visioncraft . cli/evidence_parent()."},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":814,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":819,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":820,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":822},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":827,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":830},{"target":"sym:cargo visioncraft . cli/executable().","confidence":"exact","line":831},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":836},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":843},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":844},{"target":"sym:cargo visioncraft . process/run_command().","confidence":"exact","line":850},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":854},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":854},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":858},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":858},{"target":"sym:cargo visioncraft . cli/process_status().","confidence":"exact","line":860},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":866,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . plan/QualityPlan#digest().","confidence":"inferred","line":885},{"target":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","confidence":"exact","line":909,"expands":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":911},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":911,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/execution_exit().","confidence":"exact","line":912},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":924}],"hash":"blake3:f85f4c799e989e52e1d019de0ab972275cb43e5195f141cb2ea2d324af9bb903"},{"id":"sym:cargo visioncraft . cli/load_receipts().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/load_receipts().","span":{"start_line":930,"start_col":1,"end_line":960,"end_col":2},"sig_hash":"blake3-16:c5944f1ef230b917228e3114fc3f9133","body_hash":"blake3-16:8e82d035d63b0fd789327e31b5b9794c","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft . evidence/ExecutionReceipt#"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":934},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":941},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":946,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":953},{"target":"sym:cargo visioncraft . evidence/ExecutionReceipt#parse().","confidence":"exact","line":953},{"target":"sym:cargo visioncraft . cli/receipt_artifacts().","confidence":"exact","line":954},{"target":"sym:cargo visioncraft . cli/add_artifact().","confidence":"exact","line":955,"expands":"sym:cargo visioncraft . cli/add_artifact()."}],"hash":"blake3:cc786ac0e563e162c5bd861f9c216fe9ef10f557e6eeb37a0b004e691b4aa023"},{"id":"sym:cargo visioncraft . cli/evaluate_options().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/evaluate_options().","span":{"start_line":962,"start_col":1,"end_line":1089,"end_col":2},"sig_hash":"blake3-16:e24a4e8e44d00858f88e500a666ef939","body_hash":"blake3-16:858b9ee3ab3c6ae5aa824a3fc4a3361c","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . plan/Subject#","sym:cargo visioncraft . evidence/VerifiedArtifacts#","sym:cargo visioncraft . cli/ContextFile#","sym:cargo visioncraft . evaluate/EvaluationContext#","sym:extern sealmap_corpus","sym:cargo visioncraft . evaluate/"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":963},{"target":"sym:cargo visioncraft . cli/read_plan().","confidence":"exact","line":964},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":967,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":968,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":971},{"target":"sym:cargo visioncraft . cli/selected_dirty().","confidence":"exact","line":976,"expands":"sym:cargo visioncraft . cli/selected_dirty()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":980},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":980},{"target":"sym:cargo visioncraft . cli/read_explicit().","confidence":"exact","line":986,"expands":"sym:cargo visioncraft . cli/read_explicit()."},{"target":"sym:cargo visioncraft . from_json().","confidence":"exact","line":987},{"target":"sym:cargo visioncraft . plan/Subject#validate().","confidence":"exact","line":988,"expands":"sym:cargo visioncraft . plan/Subject#validate()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":995},{"target":"sym:cargo visioncraft . evidence/VerifiedArtifacts#default().","confidence":"inferred","line":1001},{"target":"sym:cargo visioncraft . cli/load_receipts().","confidence":"exact","line":1004,"expands":"sym:cargo visioncraft . cli/load_receipts()."},{"target":"sym:cargo visioncraft . cli/ContextFile#default().","confidence":"inferred","line":1006},{"target":"sym:cargo visioncraft . cli/read_explicit().","confidence":"exact","line":1008,"expands":"sym:cargo visioncraft . cli/read_explicit()."},{"target":"sym:cargo visioncraft . from_json().","confidence":"exact","line":1009},{"target":"sym:cargo visioncraft . cli/add_artifact().","confidence":"exact","line":1016,"expands":"sym:cargo visioncraft . cli/add_artifact()."},{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":1021,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . evaluate/EvaluationContext#new().","confidence":"exact","line":1036},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":1043},{"target":"sym:extern sealmap_corpus::route::Family::named","confidence":"external","line":1049},{"target":"sym:cargo visioncraft . evaluate/","confidence":"exact","line":1053},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":1055}],"hash":"blake3:7124460731cfad155822a2220dc78fdfd21fd8ce1785f8349845d2bf7272b849"},{"id":"sym:cargo visioncraft . cli/execute().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/execute().","span":{"start_line":1091,"start_col":1,"end_line":1130,"end_col":2},"sig_hash":"blake3-16:46912e87ff2e1ea76267f5fc634b601d","body_hash":"blake3-16:38f8733b2f66f86957663943eeb3898d","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft . deepsec/"],"calls":[{"target":"sym:cargo visioncraft . cli/init().","confidence":"exact","line":1100,"expands":"sym:cargo visioncraft . cli/init()."},{"target":"sym:cargo visioncraft . cli/read_plan().","confidence":"exact","line":1104},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":1106},{"target":"sym:cargo visioncraft . cli/run().","confidence":"exact","line":1118,"expands":"sym:cargo visioncraft . cli/run()."},{"target":"sym:cargo visioncraft . cli/evaluate_options().","confidence":"exact","line":1125,"expands":"sym:cargo visioncraft . cli/evaluate_options()."},{"target":"sym:cargo visioncraft . deepsec/execute().","confidence":"exact","line":1127,"expands":"sym:cargo visioncraft . deepsec/execute()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":1127}],"hash":"blake3:b33cd48ba99d0f8f35cf65973f7f754430fcf32c4df4237059c40674dbd2c4ce"}]},{"source":"src/deepsec.rs","document":"src/deepsec.rs.md","module":"sym:cargo visioncraft . deepsec/","source_hash":"blake3:fe5f7e3e8985a7eeb253589267c66d64771af816b56d031e6022a81c9b5649ae","document_hash":"blake3:a7bd7e112ce044a49036d54efa5933063519d48a052877314b60cbe9957d3078","fragments":[{"id":"structure:src/deepsec.rs","kind":"structure","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/","span":{"start_line":1,"start_col":1,"end_line":1013,"end_col":1},"sig_hash":"blake3-16:dfca6b22e7a0f75576ee19430ce800ad","body_hash":"blake3-16:1aca4af380a6989c4105fd15f821635e","participants":["sym:cargo visioncraft . deepsec/","sym:cargo visioncraft . deepsec/Attempt#","sym:cargo visioncraft . deepsec/DeepsecOptions#","sym:cargo visioncraft . deepsec/DeepsecPolicy#","sym:cargo visioncraft . deepsec/GateError#","sym:cargo visioncraft . deepsec/StrictJson#"],"hash":"blake3:6eecc34c285fec9c493ea0145ea40bfa7badb172c994b1257ff76b6d5cbb9329"},{"id":"sym:cargo visioncraft . deepsec/DeepsecPolicy#validate().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/DeepsecPolicy#validate().","span":{"start_line":142,"start_col":5,"end_line":229,"end_col":6},"sig_hash":"blake3-16:8e9590b4e5ea930dbb967d625e57fb57","body_hash":"blake3-16:0aaf1b920c2175079b0541e62429279d","participants":["sym:cargo visioncraft . deepsec/DeepsecPolicy#","sym:cargo visioncraft . deepsec/","sym:extern url"],"calls":[{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":146},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":149},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":152},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":155},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":161},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":167},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":180},{"target":"sym:extern url::Url::parse","confidence":"external","line":183},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":184},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":192},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":200},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":206},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":216},{"target":"sym:cargo visioncraft . deepsec/duration_ms().","confidence":"exact","line":223},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":224}],"hash":"blake3:abe7fa45bd5abad24561011927a3cf90fe983f66bed974955fbc0f150c2a401a"},{"id":"sym:cargo visioncraft . deepsec/findings().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/findings().","span":{"start_line":371,"start_col":1,"end_line":410,"end_col":2},"sig_hash":"blake3-16:d958a149d303f700360dacf89d848981","body_hash":"blake3-16:d23d0fceb0331f95373edce172a94932","participants":["sym:cargo visioncraft . deepsec/","sym:extern serde_json"],"calls":[{"target":"sym:extern serde_json::from_slice","confidence":"external","line":372},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":373},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":378},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":388},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":395},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":402},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":405}],"hash":"blake3:730cdc58cc3f43348c0dce498d29c1d82277e0e08fec90504dd8015cc12953c5"},{"id":"sym:cargo visioncraft . deepsec/Attempt#command().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/Attempt#command().","span":{"start_line":484,"start_col":5,"end_line":548,"end_col":6},"sig_hash":"blake3-16:e8c318eaf968b6ab917a2c6d444e8f2e","body_hash":"blake3-16:ef8d2a7f7c72094b0cb60dabb4f9b121","participants":["sym:cargo visioncraft . deepsec/Attempt#","sym:cargo visioncraft . deepsec/","sym:cargo visioncraft . process/","sym:extern serde_json"],"calls":[{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":497},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":500},{"target":"sym:cargo visioncraft . deepsec/environment().","confidence":"exact","line":505},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":511},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":512},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":509},{"target":"sym:cargo visioncraft . process/run_command().","confidence":"exact","line":515},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":516},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":517},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":528},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":529},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":526},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":534},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":537},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":538},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":542},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":546}],"hash":"blake3:0e56cbbb57cdab018658379f226bc56185480bd619b7b7f2166c99bcb40c0c55"},{"id":"sym:cargo visioncraft . deepsec/execute().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/execute().","span":{"start_line":571,"start_col":1,"end_line":975,"end_col":2},"sig_hash":"blake3-16:0ba905b365d196f55d4ed680e35ea604","body_hash":"blake3-16:3dc354700b8e8a66aff3d048432af924","participants":["sym:cargo visioncraft . deepsec/","sym:cargo visioncraft .","sym:cargo visioncraft . deepsec/DeepsecPolicy#","sym:extern serde_json","sym:cargo visioncraft . process/","sym:extern tempfile","sym:cargo visioncraft . deepsec/Attempt#","sym:extern recorded"],"calls":[{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":588},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":593},{"target":"sym:cargo visioncraft . from_json().","confidence":"exact","line":598},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":599},{"target":"sym:cargo visioncraft . deepsec/DeepsecPolicy#[Default]default().","confidence":"exact","line":600},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":619},{"target":"sym:cargo visioncraft . deepsec/root_for().","confidence":"exact","line":624},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":632},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":633},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":634},{"target":"sym:extern serde_json::to_string_pretty","confidence":"external","line":695},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":696},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":704},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":711},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":713},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":715},{"target":"sym:cargo visioncraft . deepsec/workspace_lock().","confidence":"exact","line":719},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":721},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":723},{"target":"sym:cargo visioncraft . process/private_file().","confidence":"exact","line":724},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":727},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":728},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":725},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":731},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":735},{"target":"sym:extern serde_json::to_string_pretty","confidence":"external","line":741},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":742},{"target":"sym:extern tempfile::NamedTempFile::new_in","confidence":"external","line":744},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":749},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":762,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/supported_version().","confidence":"exact","line":782},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":783},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":788,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":799,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:extern recorded::select","confidence":"external","line":810},{"target":"sym:extern recorded::snapshot","confidence":"external","line":811},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":814},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":815},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":812},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":818},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":845,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":847},{"target":"sym:extern recorded::pending","confidence":"external","line":856},{"target":"sym:extern recorded::run_files","confidence":"external","line":860},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":877,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":879},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":882},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":885},{"target":"sym:extern recorded::snapshot","confidence":"external","line":890},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":893},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":894},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":891},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":897},{"target":"sym:extern recorded::validate_review","confidence":"external","line":899},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":919,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":921},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":923},{"target":"sym:cargo visioncraft . deepsec/findings().","confidence":"exact","line":924,"expands":"sym:cargo visioncraft . deepsec/findings()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":926},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":965},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":966},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":963},{"target":"sym:extern serde_json::to_string_pretty","confidence":"external","line":970},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":971}],"hash":"blake3:8fd1ce1ed88cc8c90a1a8107ad0c2c15c5f9a973974decf767c1e1bdf4743b4c"}]},{"source":"src/deepsec_evidence.rs","document":"src/deepsec_evidence.rs.md","module":"sym:cargo visioncraft . deepsec_evidence/","source_hash":"blake3:7bdca6b97bbbee14a261123c7f4f1a363cf86abefbaf059141d6e3f8985a36d2","document_hash":"blake3:c32144af4d919d8b30234481ac770eff44d2a1f62ba272789dd3844dd10f0fd2","fragments":[{"id":"structure:src/deepsec_evidence.rs","kind":"structure","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/","span":{"start_line":1,"start_col":1,"end_line":317,"end_col":1},"sig_hash":"blake3-16:d29639f733f43b721a769946fd5c16ea","body_hash":"blake3-16:d66f6f33f98bccb4f22f19fb1b0f7824","participants":["sym:cargo visioncraft . deepsec_evidence/"],"hash":"blake3:2b62a4deed164da5864a4a3b4a5e4bcd5cf0545d80b644f32199c4c096571d9d"},{"id":"sym:cargo visioncraft . deepsec_evidence/confined().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/confined().","span":{"start_line":15,"start_col":1,"end_line":37,"end_col":2},"sig_hash":"blake3-16:339a3f31cc29d571f0d49cac65efa8cf","body_hash":"blake3-16:bfc51a62ae369d14245e4fe1e398ad60","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:cargo visioncraft .","sym:extern visioncraft"],"calls":[{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":16},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":20},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":29},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":33}],"hash":"blake3:b8c9c4216ed7327069ac7d1d1e50af8df2c6387d1660f7931168280d9a740822"},{"id":"sym:cargo visioncraft . deepsec_evidence/snapshot().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/snapshot().","span":{"start_line":38,"start_col":1,"end_line":60,"end_col":2},"sig_hash":"blake3-16:f9fca86ed05e6dea51f36aa77af98298","body_hash":"blake3-16:92e1f22220e61aed17b21bca7709b198","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft","sym:cargo visioncraft ."],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":40},{"target":"sym:cargo visioncraft . deepsec_evidence/confined().","confidence":"exact","line":46,"expands":"sym:cargo visioncraft . deepsec_evidence/confined()."},{"target":"sym:extern visioncraft::read_bounded","confidence":"inferred","line":46},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":49},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":56}],"hash":"blake3:5653bc15ccdd69ddf29a8b3373e42cc5d25cac283259f0cef32cb2a6d5713278"},{"id":"sym:cargo visioncraft . deepsec_evidence/select().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/select().","span":{"start_line":61,"start_col":1,"end_line":169,"end_col":2},"sig_hash":"blake3-16:cc9a89e8f0905b3cb12ddfe8572273b4","body_hash":"blake3-16:a235aab603da0aabd165ee2efd5dc868","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft"],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":71},{"target":"sym:extern visioncraft::read_bounded","confidence":"inferred","line":75},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":103},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":111},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":126},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":132},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":140},{"target":"sym:cargo visioncraft . deepsec_evidence/confined().","confidence":"exact","line":146,"expands":"sym:cargo visioncraft . deepsec_evidence/confined()."},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":160},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":162}],"hash":"blake3:5bb9a75aa00caea45c6e4b56b2814cf5c9c73123ebbc47fc505690ae8c94d101"},{"id":"sym:cargo visioncraft . deepsec_evidence/run_files().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/run_files().","span":{"start_line":170,"start_col":1,"end_line":193,"end_col":2},"sig_hash":"blake3-16:6da82f7f40f25f96425a127fb162af24","body_hash":"blake3-16:f0009e0c5095006ec53f6e0e20d411c1","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft"],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":176},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":178},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":181},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":182},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":184}],"hash":"blake3:1624786ac1edaf9933c59e02458c9e8a45069628a872c991e089a8730adc656e"},{"id":"sym:cargo visioncraft . deepsec_evidence/validate_review().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/validate_review().","span":{"start_line":220,"start_col":1,"end_line":317,"end_col":2},"sig_hash":"blake3-16:48c209a2019e0cdfb19ce0ddd22d8346","body_hash":"blake3-16:bdc3f563f8b939e53ba3780bfde17d48","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern sealmap_corpus","sym:extern serde_json","sym:extern visioncraft","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . deepsec_evidence/run_files().","confidence":"exact","line":229,"expands":"sym:cargo visioncraft . deepsec_evidence/run_files()."},{"target":"sym:cargo visioncraft . deepsec_evidence/object().","confidence":"exact","line":230},{"target":"sym:extern sealmap_corpus::review::Artifact::iter","confidence":"external","line":236},{"target":"sym:cargo visioncraft . deepsec_evidence/file_record().","confidence":"exact","line":240},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":247},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":248},{"target":"sym:extern visioncraft::write_new","confidence":"inferred","line":249},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":251},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":256},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":257},{"target":"sym:extern sealmap_corpus::review::Artifact::len","confidence":"external","line":262},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":264},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":276},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":283},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":286},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":297},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":308}],"hash":"blake3:ae2141692794b47fd4e101b62646dbe9a0868370fb4b96e96f8a8df88584ea13"}]},{"source":"src/evaluate.rs","document":"src/evaluate.rs.md","module":"sym:cargo visioncraft . evaluate/","source_hash":"blake3:e2b3c4721974ba40222309382bfb4dc2a311296e18b7324982cd29215db905a1","document_hash":"blake3:49f9b9ae1dab58503421ea3705215876ab5523eeb615b17bfbd046e1320e83c3","fragments":[{"id":"structure:src/evaluate.rs","kind":"structure","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/","span":{"start_line":1,"start_col":1,"end_line":658,"end_col":1},"sig_hash":"blake3-16:9fe9b147ca2d959744dccbc9bb23ac64","body_hash":"blake3-16:39fb69207c5495b74802e2cffd67c49d","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft . evaluate/CheckOutcome#","sym:cargo visioncraft . evaluate/CheckReport#","sym:cargo visioncraft . evaluate/EvaluationContext#","sym:cargo visioncraft . evaluate/ExpectationReport#","sym:cargo visioncraft . evaluate/GateOutcome#","sym:cargo visioncraft . evaluate/GateReport#"],"hash":"blake3:d5091dfff7bb58c6eb3e49cacb4b5589dcaf0e603efe16f2f4b6f4f74c0df81b"},{"id":"sym:cargo visioncraft . evaluate/check_receipt().","kind":"sequence","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/check_receipt().","span":{"start_line":160,"start_col":1,"end_line":273,"end_col":2},"sig_hash":"blake3-16:ee70d752233f4499288b800fcec0a414","body_hash":"blake3-16:18e0c7a71c752fd52f17a4f9b6b7d029","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft . evidence/ExecutionReceipt#","sym:cargo visioncraft . plan/","sym:cargo visioncraft . evidence/VerifiedArtifacts#"],"calls":[{"target":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","confidence":"exact","line":168,"expands":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate()."},{"target":"sym:cargo visioncraft . plan/same_inputs().","confidence":"exact","line":177},{"target":"sym:cargo visioncraft . evaluate/context_limits().","confidence":"exact","line":183},{"target":"sym:cargo visioncraft . evaluate/age_limit().","confidence":"exact","line":184},{"target":"sym:cargo visioncraft . evidence/VerifiedArtifacts#byte_len().","confidence":"inferred","line":211}],"hash":"blake3:ea42ed5e2650324925cfd3f057ff96494c704a9fb432daa12fdfe317e1020a4c"},{"id":"sym:cargo visioncraft . evaluate/assessment_binding().","kind":"sequence","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/assessment_binding().","span":{"start_line":298,"start_col":1,"end_line":320,"end_col":2},"sig_hash":"blake3-16:e2d6db985ebd381da5d83e24ce107563","body_hash":"blake3-16:7b52282e846da93f2cde20af7045a03b","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":307},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":311},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":312},{"target":"sym:cargo visioncraft . evaluate/age_limit().","confidence":"exact","line":317},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":316}],"hash":"blake3:30162b56ccfa772885e62b9a777b4781fbd01a3957b7eb431ef2feb04c8d50e9"},{"id":"sym:cargo visioncraft . evaluate/expectation_report().","kind":"sequence","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/expectation_report().","span":{"start_line":322,"start_col":1,"end_line":524,"end_col":2},"sig_hash":"blake3-16:60bd522cd3ba06f3d9da1f7b3e90b52b","body_hash":"blake3-16:e4d1797b13f584d6f345f1601b1187e9","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft .","sym:extern sealmap_corpus"],"calls":[{"target":"sym:cargo visioncraft . evaluate/referenced_check().","confidence":"exact","line":333},{"target":"sym:cargo visioncraft . evaluate/referenced_check().","confidence":"exact","line":336},{"target":"sym:cargo visioncraft . evaluate/referenced_check().","confidence":"exact","line":339},{"target":"sym:cargo visioncraft . evaluate/assessment_binding().","confidence":"exact","line":371,"expands":"sym:cargo visioncraft . evaluate/assessment_binding()."},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":381},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":382},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":383},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":380},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":386},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":391},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":400},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":404},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":411},{"target":"sym:extern sealmap_corpus::route::cross_family_with","confidence":"external","line":421},{"target":"sym:cargo visioncraft . evaluate/assessment_binding().","confidence":"exact","line":479,"expands":"sym:cargo visioncraft . evaluate/assessment_binding()."},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":490},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":490},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":489}],"hash":"blake3:621bb154f0bc58def0d9b99839bfb5f7f07500da87de83f718956d20bb7d43f5"}]},{"source":"src/evidence.rs","document":"src/evidence.rs.md","module":"sym:cargo visioncraft . evidence/","source_hash":"blake3:edfe990a885f2bcad685855fe0c87e11878174d676e4414f4f9448e818ca520a","document_hash":"blake3:92db7d2db5b346b252f2fd1d9472793cfc0dda06b4ac5f891e0e98a8629fc804","fragments":[{"id":"structure:src/evidence.rs","kind":"structure","document":"src/evidence.rs.md","symbol":"sym:cargo visioncraft . evidence/","span":{"start_line":1,"start_col":1,"end_line":292,"end_col":1},"sig_hash":"blake3-16:af11808614b221a0d9791b5c9c0aa422","body_hash":"blake3-16:07ca5c0150b9e722b1428c85557ebe66","participants":["sym:cargo visioncraft . evidence/","sym:cargo visioncraft . evidence/Actor#","sym:cargo visioncraft . evidence/AuditReceipt#","sym:cargo visioncraft . evidence/AuditVerdict#","sym:cargo visioncraft . evidence/ExecutionReceipt#","sym:cargo visioncraft . evidence/ManualObservation#","sym:cargo visioncraft . evidence/ProcessStatus#","sym:cargo visioncraft . evidence/ReportedResult#","sym:cargo visioncraft . evidence/VerifiedArtifacts#"],"hash":"blake3:4cac75df033fe3d821a9d0b2c1862cba2880e53086a68efdbae14c83e5830ef8"},{"id":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","kind":"sequence","document":"src/evidence.rs.md","symbol":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","span":{"start_line":107,"start_col":5,"end_line":178,"end_col":6},"sig_hash":"blake3-16:ba67f81a1ab12cfa2f20da686b32f5f9","body_hash":"blake3-16:85e6fc9a46be325577dbc0b80d49e394","participants":["sym:cargo visioncraft . evidence/ExecutionReceipt#","sym:cargo visioncraft .","sym:cargo visioncraft . plan/Subject#","sym:cargo visioncraft . plan/Invocation#","sym:cargo visioncraft . plan/"],"calls":[{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":113},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":115},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":115},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":114},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":118},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":118},{"target":"sym:cargo visioncraft . plan/Subject#validate().","confidence":"exact","line":119,"expands":"sym:cargo visioncraft . plan/Subject#validate()."},{"target":"sym:cargo visioncraft . plan/Invocation#validate().","confidence":"exact","line":120,"expands":"sym:cargo visioncraft . plan/Invocation#validate()."},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":122},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":121},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":126},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":126},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":129},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":129},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":131},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":135},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":140},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":144},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":149},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":155},{"target":"sym:cargo visioncraft . plan/validate_input_paths().","confidence":"exact","line":157},{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":161},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":160},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":167},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":166},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":172},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":172},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":171},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":175}],"hash":"blake3:5d5543a5441c2972246e77d27188c7df4e53e2c8f859470ae0c0453e4c16b416"}]},{"source":"src/lib.rs","document":"src/lib.rs.md","module":"sym:cargo visioncraft .","source_hash":"blake3:337326f4db730b3c5a5b0457e94f425a596bc8dd6d765e3e51bc9d78bc56b9ad","document_hash":"blake3:67ae0071bf62c3820f59479d664ab7c9a51ea020147d508d84659a58c006f878","fragments":[{"id":"structure:src/lib.rs","kind":"structure","document":"src/lib.rs.md","symbol":"sym:cargo visioncraft .","span":{"start_line":1,"start_col":1,"end_line":129,"end_col":1},"sig_hash":"blake3-16:ef5f0989f89148798c9d4374da243656","body_hash":"blake3-16:117cef759286f6dbd432e1a52012ceff","participants":["sym:cargo visioncraft .","sym:cargo visioncraft . ContractError#"],"hash":"blake3:79e67b1adcabdc35ac57b7f5efcfb3e829837c5a64d36093531f2b87d50b14ad"}]},{"source":"src/main.rs","document":"src/main.rs.md","module":"sym:cargo visioncraft_main .","source_hash":"blake3:99d2860c356b50b40860a89032581ec5c2ae5c16e89fca73d9a59be073f78872","document_hash":"blake3:29b1d11fb16398576b5963e7e60910c3a3a592b7f1368c77b460e33966c7659e","fragments":[{"id":"structure:src/main.rs","kind":"structure","document":"src/main.rs.md","symbol":"sym:cargo visioncraft_main .","span":{"start_line":1,"start_col":1,"end_line":38,"end_col":1},"sig_hash":"blake3-16:be7e0aa42067d3874629adeff2b5a523","body_hash":"blake3-16:74e980764c560ee52cd65267ced20ea5","participants":["sym:cargo visioncraft_main ."],"hash":"blake3:6072a92081ad96885a435ab18fa15f7156552c9f5a91ffd3b893d30664f7c127"}]},{"source":"src/plan.rs","document":"src/plan.rs.md","module":"sym:cargo visioncraft . plan/","source_hash":"blake3:a0eaf6b6e34139a3b02ddc3d521d69dc4c064884b96dfe85585b1a1e7da2107d","document_hash":"blake3:52a11da34333ac5b351ee8aecb9f323047782e5c9a5a9c3d35b3707c159fa8f8","fragments":[{"id":"structure:src/plan.rs","kind":"structure","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/","span":{"start_line":1,"start_col":1,"end_line":413,"end_col":1},"sig_hash":"blake3-16:a24f0f42e161b5767c66583d880ff1c1","body_hash":"blake3-16:244666ed06402316b2c9d9f1e3d97726","participants":["sym:cargo visioncraft . plan/","sym:cargo visioncraft . plan/CheckSpec#","sym:cargo visioncraft . plan/Evaluator#","sym:cargo visioncraft . plan/EvidenceCategory#","sym:cargo visioncraft . plan/Expectation#","sym:cargo visioncraft . plan/GatePolicy#","sym:cargo visioncraft . plan/Invocation#","sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft . plan/Stabilizer#","sym:cargo visioncraft . plan/Subject#"],"hash":"blake3:c3b2d48210fcb0809c8dffe5957419f886988159fb60f056c51dd599ada41860"},{"id":"sym:cargo visioncraft . plan/Subject#validate().","kind":"sequence","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/Subject#validate().","span":{"start_line":36,"start_col":5,"end_line":58,"end_col":6},"sig_hash":"blake3-16:cc5a01905f372f11d7204d0e8ae9b415","body_hash":"blake3-16:5c8417ac75b7f4969f36b4094d1bba88","participants":["sym:cargo visioncraft . plan/Subject#","sym:cargo visioncraft .","sym:cargo visioncraft . plan/"],"calls":[{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":41},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":41},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":43},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":42},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":47},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":46},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":50},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":55},{"target":"sym:cargo visioncraft . plan/validate_inputs().","confidence":"exact","line":57}],"hash":"blake3:322d9507a0187eaa308b3d532d47b123850c5a0d98d5ae483d9298c64ffe0ff3"},{"id":"sym:cargo visioncraft . plan/Invocation#validate().","kind":"sequence","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/Invocation#validate().","span":{"start_line":104,"start_col":5,"end_line":137,"end_col":6},"sig_hash":"blake3-16:df6aee1d4a2a9d4b92536e69433d3c6a","body_hash":"blake3-16:49668b9727c1ac54be4cd4c716e96fee","participants":["sym:cargo visioncraft . plan/Invocation#","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":109},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":109},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":110},{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":115},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":114},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":120},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":127},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":129},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":133}],"hash":"blake3:3354fc277d9bd09a45bbea06e5bc7342f7c586064f59d475a64b2bf33d0fda57"},{"id":"sym:cargo visioncraft . plan/QualityPlan#validate().","kind":"sequence","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/QualityPlan#validate().","span":{"start_line":291,"start_col":5,"end_line":398,"end_col":6},"sig_hash":"blake3-16:fa4cb29f8ee4f18407e9aa68bcbe8d75","body_hash":"blake3-16:16e4b5b86916c3ea0a2107386a4cc734","participants":["sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft .","sym:cargo visioncraft . plan/Subject#"],"calls":[{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":296},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":297},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":301},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":301},{"target":"sym:cargo visioncraft . plan/Subject#validate().","confidence":"exact","line":302,"expands":"sym:cargo visioncraft . plan/Subject#validate()."},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":303},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":307},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":317},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":316},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":327},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":331},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":335},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":338},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":346},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":354},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":353},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":362},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":361},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":365},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":365},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":367},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":374},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":380},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":379},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":385},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":391}],"hash":"blake3:a69180a482bd092c9035df0f4320ba289ec9d3162ec8ec2442e80c95752b5e56"}]},{"source":"src/process.rs","document":"src/process.rs.md","module":"sym:cargo visioncraft . process/","source_hash":"blake3:b24b8fb96eba5f197c4a00e8da464df9d6d53b98c4db058f9b684e8da1c64e3c","document_hash":"blake3:c03e83f7bbadfe8920588aef29b50133bac05827f21474b6c72a022d5444671c","fragments":[{"id":"structure:src/process.rs","kind":"structure","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/","span":{"start_line":1,"start_col":1,"end_line":425,"end_col":1},"sig_hash":"blake3-16:7e2098952f191664fce2401b4fe2c94b","body_hash":"blake3-16:9afdf9190af30106c625ee75cfc287b4","participants":["sym:cargo visioncraft . process/","sym:cargo visioncraft . process/CapturedRun#","sym:cargo visioncraft . process/Termination#"],"hash":"blake3:16d6e3cdcb6791ae483d161c57a6207500a8f8ee76e3321bb2e9ed2fb52fdaab"},{"id":"sym:cargo visioncraft . process/run_command_with_env().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/run_command_with_env().","span":{"start_line":225,"start_col":1,"end_line":425,"end_col":2},"sig_hash":"blake3-16:60939e55bba0ee305de92ce58430f493","body_hash":"blake3-16:85047a9f67830cc53472ce1dab56e2c9","participants":["sym:cargo visioncraft . process/","sym:cargo visioncraft . plan/Invocation#","sym:extern nix"],"calls":[{"target":"sym:cargo visioncraft . plan/Invocation#validate().","confidence":"exact","line":253,"expands":"sym:cargo visioncraft . plan/Invocation#validate()."},{"target":"sym:cargo visioncraft . process/unix_now().","confidence":"exact","line":256},{"target":"sym:cargo visioncraft . process/private_file().","confidence":"exact","line":260},{"target":"sym:cargo visioncraft . process/private_file().","confidence":"exact","line":261},{"target":"sym:cargo visioncraft . process/unix_now().","confidence":"exact","line":313},{"target":"sym:cargo visioncraft . process/capture().","confidence":"exact","line":322},{"target":"sym:cargo visioncraft . process/capture().","confidence":"exact","line":330},{"target":"sym:extern nix::unistd::Pid::from_raw","confidence":"external","line":364},{"target":"sym:extern nix::sys::signal::killpg","confidence":"external","line":364},{"target":"sym:cargo visioncraft . process/signal_group().","confidence":"exact","line":384},{"target":"sym:cargo visioncraft . process/signal_group().","confidence":"exact","line":395},{"target":"sym:cargo visioncraft . process/unix_now().","confidence":"exact","line":421}],"hash":"blake3:e8e9bb5dbba17720424498f68a29d37094ccac94fc080f656c80cbde67386d59"}]}]} diff --git a/docs/diagrams/generated/_overview.md b/docs/diagrams/generated/_overview.md new file mode 100644 index 0000000..53a3429 --- /dev/null +++ b/docs/diagrams/generated/_overview.md @@ -0,0 +1,365 @@ +--- +sealmap: 2 +kind: overview +codebase: visioncraft +--- +# visioncraft overview +9 files · 151 symbols · 572 relations · 69 flows · 492 calls + +## crates +```mermaid +flowchart LR + visioncraft(["visioncraft"]) + visioncraft_main(["visioncraft_main"]) + clap{{"clap"}} + nix{{"nix"}} + recorded{{"recorded"}} + sealmap_corpus{{"sealmap_corpus"}} + serde{{"serde"}} + serde_json{{"serde_json"}} + sha2{{"sha2"}} + signal_hook{{"signal_hook"}} + tempfile{{"tempfile"}} + url{{"url"}} + visioncraft -->|"5"| clap + visioncraft -->|"17"| nix + visioncraft -->|"5"| recorded + visioncraft -->|"37"| sealmap_corpus + visioncraft -->|"14"| serde + visioncraft -->|"19"| serde_json + visioncraft -->|"3"| sha2 + visioncraft -->|"7"| tempfile + visioncraft -->|"1"| url + visioncraft_main -->|"1"| clap + visioncraft_main -->|"1"| signal_hook + visioncraft_main -->|"3"| visioncraft +``` + +## modules: visioncraft +```mermaid +flowchart LR + visioncraft["visioncraft"] + visioncraft__cli["cli"] + visioncraft__deepsec["deepsec"] + visioncraft__deepsec_evidence["deepsec_evidence"] + visioncraft__evaluate["evaluate"] + visioncraft__evidence["evidence"] + visioncraft__plan["plan"] + visioncraft__process["process"] + visioncraft -->|"7"| visioncraft__evaluate + visioncraft -->|"8"| visioncraft__evidence + visioncraft -->|"9"| visioncraft__plan + visioncraft__cli -->|"13"| visioncraft + visioncraft__cli -->|"2"| visioncraft__deepsec + visioncraft__cli -->|"3"| visioncraft__evaluate + visioncraft__cli -->|"16"| visioncraft__evidence + visioncraft__cli -->|"13"| visioncraft__plan + visioncraft__cli -->|"8"| visioncraft__process + visioncraft__deepsec -->|"3"| visioncraft + visioncraft__deepsec -->|"1"| visioncraft__plan + visioncraft__deepsec -->|"8"| visioncraft__process + visioncraft__deepsec_evidence -->|"4"| visioncraft + visioncraft__evaluate -->|"10"| visioncraft + visioncraft__evaluate -->|"15"| visioncraft__evidence + visioncraft__evaluate -->|"20"| visioncraft__plan + visioncraft__evidence -->|"20"| visioncraft + visioncraft__evidence -->|"2"| visioncraft__evaluate + visioncraft__evidence -->|"10"| visioncraft__plan + visioncraft__plan -->|"31"| visioncraft + visioncraft__process -->|"4"| visioncraft__plan +``` + +## data: visioncraft +```mermaid +erDiagram + visioncraft__cli___tCli["Cli"] { + Operation command + } + visioncraft__cli___tContextFile["ContextFile"] { + Vec[AuditReceipt] audits + Vec[ManualObservation] manual_observations + Vec[FamilyDeclaration] families + } + visioncraft__cli___tEvaluateOptions["EvaluateOptions"] { + PathBuf plan + PathBuf root + Vec[PathBuf] receipts + Option[PathBuf] context + Option[PathBuf] current_subject + Option[u64] as_of_ms + bool json + } + visioncraft__cli___tExpectationCommand["ExpectationCommand"] + visioncraft__cli___tFamilyDeclaration["FamilyDeclaration"] { + String route + String family + } + visioncraft__cli___tGateCommand["GateCommand"] + visioncraft__cli___tInitOptions["InitOptions"] { + PathBuf root + PathBuf out + Vec[String] input + String id + String check + Option[String] repository + String configuration + String cwd + Vec[String] env + u64 timeout_ms + u64 max_output_bytes + Vec[String] command + } + visioncraft__cli___tOperation["Operation"] + visioncraft__cli___tPlanCommand["PlanCommand"] + visioncraft__cli___tRunOptions["RunOptions"] { + PathBuf plan + PathBuf root + Option[String] check + bool all + PathBuf out + } + visioncraft__deepsec___tAttempt["Attempt"] { + __aDeepsecPolicy policy "&'a DeepsecPolicy" + __aPath report "&'a Path" + __aAtomicBool cancelled "&'a AtomicBool" + Instant started + Duration deadline + u32 sequence + } + visioncraft__deepsec___tDeepsecOptions["DeepsecOptions"] { + Option[String] diff + bool diff_working + bool diff_staged + Option[PathBuf] files_from + bool full + bool scan_only + Option[PathBuf] root + Option[PathBuf] report_dir + Option[String] policy_json + Option[String] fail_on + Option[String] thinking_level + Option[String] agent + Option[String] model + Option[String] model_auth + bool dry_run + } + visioncraft__deepsec___tDeepsecPolicy["DeepsecPolicy"] { + bool enabled + String agent + String model_auth + String model + String thinking_level + String fail_on + String max_duration + u32 batch_size + u32 concurrency + String ai_provider + String ai_api_key_env + String ai_base_url + String policy_source + u64 max_output_bytes + } + visioncraft__evaluate___tCheckOutcome["CheckOutcome"] + visioncraft__evaluate___tCheckReport["CheckReport"] { + String id + bool required + Option[String] attempt_id + CheckOutcome outcome + Vec[String] reasons + } + visioncraft__evaluate___tEvaluationContext["EvaluationContext"] { + u64 now_ms + __aSubject current_subject "&'a Subject" + __aVerifiedArtifacts verified "&'a VerifiedArtifacts" + __a[String] ancestor_revisions "&'a [String]" + FamilyCatalogue families + __a[AuditReceipt] audits "&'a [AuditReceipt]" + __a[ManualObservation] manual_observations "&'a [ManualObservation]" + } + visioncraft__evaluate___tExpectationReport["ExpectationReport"] { + String id + bool required + CheckOutcome outcome + Vec[String] reasons + } + visioncraft__evaluate___tGateOutcome["GateOutcome"] + visioncraft__evaluate___tGateReport["GateReport"] { + GateOutcome outcome + usize required_checks + usize passed_required_checks + Vec[CheckReport] checks + Vec[ExpectationReport] expectations + Vec[String] errors + } + visioncraft__evidence___tActor["Actor"] { + String agent_id + String attempt_id + String model + } + visioncraft__evidence___tAuditReceipt["AuditReceipt"] { + String expectation_id + String plan_sha256 + Subject subject + Actor producer + Actor reviewer + String probe_check + AuditVerdict verdict + String observed + Artifact artifact + u64 captured_at_ms + } + visioncraft__evidence___tAuditVerdict["AuditVerdict"] + visioncraft__evidence___tExecutionReceipt["ExecutionReceipt"] { + u32 version + String attempt_id + String plan_sha256 + String check_id + Subject subject + Invocation invocation + String executable + Option[String] executable_sha256 + Option[String] tool_version + u64 started_at_ms + u64 finished_at_ms + u64 elapsed_ms + ProcessStatus process + Option[i32] exit_code + Option[i32] signal + bool capture_complete + Option[Artifact] stdout + Option[Artifact] stderr + Vec[Artifact] inputs_after + Option[Vec[String]] observed_scope + Vec[String] observed_tests + Option[ReportedResult] reported + Option[String] diagnostic + } + visioncraft__evidence___tManualObservation["ManualObservation"] { + String expectation_id + String plan_sha256 + Subject subject + String observer + String observed + AuditVerdict verdict + Artifact artifact + u64 captured_at_ms + } + visioncraft__evidence___tProcessStatus["ProcessStatus"] + visioncraft__evidence___tReportedResult["ReportedResult"] { + String adapter + CheckOutcome outcome + String reason + Artifact artifact + } + visioncraft__evidence___tVerifiedArtifacts["VerifiedArtifacts"] { + BTreeMap[(String_String)_u64] entries "BTreeMap<(String, String), u64>" + } + visioncraft__plan___tCheckSpec["CheckSpec"] { + String id + bool required + Invocation invocation + Evaluator evaluator + Vec[String] scope + } + visioncraft__plan___tEvaluator["Evaluator"] + visioncraft__plan___tEvidenceCategory["EvidenceCategory"] + visioncraft__plan___tExpectation["Expectation"] { + String id + String claim + bool required + EvidenceCategory category + Vec[String] checks + bool regression_critical + Option[Stabilizer] stabilizer + Option[String] positive_control + bool independent_audit + Option[String] limitation + } + visioncraft__plan___tGatePolicy["GatePolicy"] { + Option[u64] max_age_ms + bool require_observed_scope + } + visioncraft__plan___tInvocation["Invocation"] { + String program + Vec[String] args + String cwd + Vec[String] env + u64 timeout_ms + u64 max_output_bytes + } + visioncraft__plan___tQualityPlan["QualityPlan"] { + u32 version + String id + Subject subject + Vec[CheckSpec] checks + Vec[Expectation] expectations + GatePolicy policy + } + visioncraft__plan___tStabilizer["Stabilizer"] { + String check_id + String test_id + } + visioncraft__plan___tSubject["Subject"] { + String repository + String revision + String configuration + bool dirty + Option[Artifact] working_tree + Vec[Artifact] inputs + } + visioncraft__process___tCapturedRun["CapturedRun"] { + Termination termination + Option[i32] exit_code + Option[i32] signal + u64 started_at_ms + u64 finished_at_ms + u64 elapsed_ms + PathBuf stdout + PathBuf stderr + Option[String] error + } + visioncraft__process___tTermination["Termination"] + visioncraft__cli___tCli ||--|| visioncraft__cli___tOperation : "command" + visioncraft__cli___tContextFile ||--o{ visioncraft__evidence___tAuditReceipt : "audits" + visioncraft__cli___tContextFile ||--o{ visioncraft__evidence___tManualObservation : "manual_observations" + visioncraft__cli___tContextFile ||--o{ visioncraft__cli___tFamilyDeclaration : "families" + visioncraft__cli___tExpectationCommand ||--|| visioncraft__cli___tEvaluateOptions : "Check" + visioncraft__cli___tGateCommand ||--|| visioncraft__cli___tEvaluateOptions : "Evaluate" + visioncraft__cli___tOperation ||--|| visioncraft__cli___tPlanCommand : "Plan" + visioncraft__cli___tOperation ||--|| visioncraft__cli___tRunOptions : "Run" + visioncraft__cli___tOperation ||--|| visioncraft__cli___tEvaluateOptions : "Evaluate" + visioncraft__cli___tOperation ||--|| visioncraft__cli___tGateCommand : "Gate" + visioncraft__cli___tOperation ||--|| visioncraft__cli___tExpectationCommand : "Expectations" + visioncraft__cli___tOperation ||--|| visioncraft__deepsec___tDeepsecOptions : "Deepsec" + visioncraft__cli___tPlanCommand ||--|| visioncraft__cli___tInitOptions : "Init" + visioncraft__deepsec___tAttempt ||..|| visioncraft__deepsec___tDeepsecPolicy : "policy" + visioncraft__evaluate___tCheckReport ||--|| visioncraft__evaluate___tCheckOutcome : "outcome" + visioncraft__evaluate___tEvaluationContext ||..|| visioncraft__plan___tSubject : "current_subject" + visioncraft__evaluate___tEvaluationContext ||..|| visioncraft__evidence___tVerifiedArtifacts : "verified" + visioncraft__evaluate___tEvaluationContext ||..|| visioncraft__evidence___tAuditReceipt : "audits" + visioncraft__evaluate___tEvaluationContext ||..|| visioncraft__evidence___tManualObservation : "manual_observations" + visioncraft__evaluate___tExpectationReport ||--|| visioncraft__evaluate___tCheckOutcome : "outcome" + visioncraft__evaluate___tGateReport ||--|| visioncraft__evaluate___tGateOutcome : "outcome" + visioncraft__evaluate___tGateReport ||--o{ visioncraft__evaluate___tCheckReport : "checks" + visioncraft__evaluate___tGateReport ||--o{ visioncraft__evaluate___tExpectationReport : "expectations" + visioncraft__evidence___tAuditReceipt ||--|| visioncraft__plan___tSubject : "subject" + visioncraft__evidence___tAuditReceipt ||--|| visioncraft__evidence___tActor : "producer" + visioncraft__evidence___tAuditReceipt ||--|| visioncraft__evidence___tActor : "reviewer" + visioncraft__evidence___tAuditReceipt ||--|| visioncraft__evidence___tAuditVerdict : "verdict" + visioncraft__evidence___tExecutionReceipt ||--|| visioncraft__plan___tSubject : "subject" + visioncraft__evidence___tExecutionReceipt ||--|| visioncraft__plan___tInvocation : "invocation" + visioncraft__evidence___tExecutionReceipt ||--|| visioncraft__evidence___tProcessStatus : "process" + visioncraft__evidence___tExecutionReceipt ||--o| visioncraft__evidence___tReportedResult : "reported" + visioncraft__evidence___tManualObservation ||--|| visioncraft__plan___tSubject : "subject" + visioncraft__evidence___tManualObservation ||--|| visioncraft__evidence___tAuditVerdict : "verdict" + visioncraft__evidence___tReportedResult ||--|| visioncraft__evaluate___tCheckOutcome : "outcome" + visioncraft__plan___tCheckSpec ||--|| visioncraft__plan___tInvocation : "invocation" + visioncraft__plan___tCheckSpec ||--|| visioncraft__plan___tEvaluator : "evaluator" + visioncraft__plan___tExpectation ||--|| visioncraft__plan___tEvidenceCategory : "category" + visioncraft__plan___tExpectation ||--o| visioncraft__plan___tStabilizer : "stabilizer" + visioncraft__plan___tQualityPlan ||--|| visioncraft__plan___tSubject : "subject" + visioncraft__plan___tQualityPlan ||--o{ visioncraft__plan___tCheckSpec : "checks" + visioncraft__plan___tQualityPlan ||--o{ visioncraft__plan___tExpectation : "expectations" + visioncraft__plan___tQualityPlan ||--|| visioncraft__plan___tGatePolicy : "policy" + visioncraft__process___tCapturedRun ||--|| visioncraft__process___tTermination : "termination" +``` diff --git a/docs/diagrams/generated/src/cli.rs.md b/docs/diagrams/generated/src/cli.rs.md new file mode 100644 index 0000000..6fe225c --- /dev/null +++ b/docs/diagrams/generated/src/cli.rs.md @@ -0,0 +1,565 @@ +--- +sealmap: 2 +source: src/cli.rs +module: "sym:cargo visioncraft . cli/" +language: rust +source_hash: blake3:e883c6b79fba490bdf06476058ca4078ae6ce7a147e4308b65afd6c1326bdb7d +lines: 1130 +fragments: 17 +--- +# `sym:cargo visioncraft . cli/` · src/cli.rs +> Native filesystem and command-line adapter for the deterministic core. + +## structure +```mermaid +classDiagram + direction LR + class visioncraft__cli___tCli["Cli"] { + <> + -command: Operation + } + class visioncraft__cli___tCliError["CliError"] { + <> + +code: i32 + +message: String + } + class visioncraft__cli["visioncraft::cli"] { + <> + +execute(cli: Cli, cancelled: &AtomicBool) Result#lt;i32, CliError#gt; + } + class visioncraft__cli___tOperation["Operation"] { + <> + } + visioncraft__cli ..> visioncraft__cli___tCli + visioncraft__cli ..> visioncraft__cli___tCliError + visioncraft__cli___tCli *-- visioncraft__cli___tOperation : command +``` + +## `sym:cargo visioncraft . cli/confined().` +`fn confined(root: &Path, relative: &str, directory: bool) -> Result` · L218-L244 +```mermaid +sequenceDiagram + participant visioncraft__cli as cli mod + participant visioncraft as visioncraft mod + opt relative == #quot;.#quot; && directory + Note over visioncraft__cli: return Ok(root.to_owned()) + end + visioncraft__cli->>visioncraft: crate::relative_path(relative) + opt !crate::relative_path(relative) + visioncraft__cli->>visioncraft__cli: error(2, #quot;path must be…) + Note over visioncraft__cli: return Err(error(2, #quot;path must be confined and relative… + end + loop for component in Path::new(relative).components() + opt let-else + visioncraft__cli->>visioncraft__cli: error(2, #quot;invalid rela…) + Note over visioncraft__cli: return Err(error(2, #quot;invalid relative path#quot;)) + end + opt metadata.file_type().is_symlink() + visioncraft__cli->>visioncraft__cli: error(2, #quot;symlinks ins…) + Note over visioncraft__cli: return Err(error(2, #quot;symlinks inside source/evidence ro… + end + end + opt (directory && !metadata.is_dir()) || (!directory && … + visioncraft__cli->>visioncraft__cli: error(2, #quot;expected an …) + Note over visioncraft__cli: return Err(error(2, #quot;expected an ordinary file or direc… + end +``` + +## `sym:cargo visioncraft . cli/read_explicit().` +`fn read_explicit(path: &Path, limit: u64) -> Result<(PathBuf, Vec), CliError>` · L266-L278 +```mermaid +sequenceDiagram + participant visioncraft__cli as cli mod + visioncraft__cli->>visioncraft__cli: root(unwrap_or())? + opt via ok_or_else + visioncraft__cli->>visioncraft__cli: error(2, #quot;input filena…) + end + visioncraft__cli->>visioncraft__cli: confined(&parent, name, false)? + visioncraft__cli->>visioncraft__cli: read_bounded(&file, limit)? +``` + +## `sym:cargo visioncraft . cli/output_path().` +`fn output_path(path: &Path) -> Result` · L280-L305 +```mermaid +sequenceDiagram + participant visioncraft__cli as cli mod + loop for component in absolute.components() + opt Component::ParentDir + visioncraft__cli->>visioncraft__cli: error(2, #quot;output path …) + Note over visioncraft__cli: return Err(error(2, #quot;output path cannot traverse parent… + end + alt Ok(m) if m.file_type().is_symlink() + visioncraft__cli->>visioncraft__cli: error(2, #quot;symlinked ou…) + Note over visioncraft__cli: return Err(error(2, #quot;symlinked output paths are refused… + else Ok(_) if current == absolute + visioncraft__cli->>visioncraft__cli: error(2, #quot;output alrea…) + Note over visioncraft__cli: return Err(error(2, #quot;output already exists#quot;)) + else Ok(_) + visioncraft__cli->>visioncraft__cli: error(2, #quot;output paren…) + Note over visioncraft__cli: return Err(error(2, #quot;output parent is not a directory#quot;)) + else Err(e) + visioncraft__cli->>visioncraft__cli: io_error(e) + Note over visioncraft__cli: return Err(io_error(e)) + end + end +``` + +## `sym:cargo visioncraft . cli/write_new().` +`fn write_new(path: &Path, bytes: &[u8]) -> Result<(), CliError>` · L307-L319 +```mermaid +sequenceDiagram + participant visioncraft__cli as cli mod + participant _tempfile as tempfile ext + visioncraft__cli->>visioncraft__cli: output_path(path)? + opt via ok_or_else + visioncraft__cli->>visioncraft__cli: error(2, #quot;output lacks…) + end + visioncraft__cli->>_tempfile: NamedTempFile::new_in(parent) + opt via map_err + visioncraft__cli->>visioncraft__cli: io_error(e.error) + end +``` + +## `sym:cargo visioncraft . cli/git().` +`fn git(root: &Path, args: &[&str], cancelled: &AtomicBool) -> Result` · L338-L418 +```mermaid +sequenceDiagram + participant visioncraft__cli as cli mod + participant _tempfile as tempfile ext + participant visioncraft__process as process mod + visioncraft__cli->>_tempfile: Builder::new() + visioncraft__cli->>_tempfile: Builder::prefix(#quot;visioncraft-…) + visioncraft__cli->>_tempfile: Builder::permissions(from_mode()) + visioncraft__cli->>_tempfile: Builder::tempdir() + opt via ok_or_else + visioncraft__cli->>visioncraft__cli: error(78, #quot;source root …) + end + visioncraft__cli->>visioncraft__process: process::run_command_with_env(&invocation, root, path()… + alt Termination::Completed if captured.exit_code.is_some() + visioncraft__cli->>visioncraft__cli: read_bounded(&captured.stdout, limit)? + else Termination::Unavailable + visioncraft__cli->>visioncraft__cli: error(78, #quot;Git metadata…) + else Termination::TimedOut + visioncraft__cli->>visioncraft__cli: error(124, #quot;Git metadata…) + else Termination::Interrupted + visioncraft__cli->>visioncraft__cli: error(130, #quot;Git metadata…) + else _ + visioncraft__cli->>visioncraft__cli: error(70, #quot;Git metadata…) + end +``` + +## `sym:cargo visioncraft . cli/revision().` +`fn revision(root: &Path, cancelled: &AtomicBool) -> Result` · L420-L430 +```mermaid +sequenceDiagram + participant visioncraft__cli as cli mod + participant visioncraft as visioncraft mod + visioncraft__cli->>visioncraft__cli: git(root, &_, cancelled)? + opt via map_err + visioncraft__cli->>visioncraft__cli: error(2, #quot;Git revision…) + end + visioncraft__cli->>visioncraft: crate::hex(&revision, &_) + opt !output.success ||!crate::hex(&revision, &[40, 64]) + visioncraft__cli->>visioncraft__cli: error(2, #quot;source root …) + Note over visioncraft__cli: return Err(error(2, #quot;source root requires a committed G… + end +``` + +## `sym:cargo visioncraft . cli/selected_dirty().` +`fn selected_dirty(root: &Path, paths: &[String], cancelled: &AtomicBool) -> Result` · L432-L497 +```mermaid +sequenceDiagram + participant visioncraft__cli as cli mod + participant visioncraft as visioncraft mod + visioncraft__cli->>visioncraft__cli: git(root, &args, cancelled)? + opt !output.success + visioncraft__cli->>visioncraft__cli: error(70, #quot;could not in…) + Note over visioncraft__cli: return Err(error(70, #quot;could not inspect selected Git in… + end + loop for row in output.stdout.split(| b | * b == 0).filter(|… + opt via ok_or_else + visioncraft__cli->>visioncraft__cli: error(70, #quot;invalid Git …) + end + opt via map_err + visioncraft__cli->>visioncraft__cli: error(70, #quot;invalid Git …) + end + opt via map_err + visioncraft__cli->>visioncraft__cli: error(70, #quot;selected Git…) + end + end + loop for path in paths + opt let-else + Note over visioncraft__cli: return Ok(true) + end + visioncraft__cli->>visioncraft: crate::hex(object, &_) + opt !crate::hex(object, &[40, 64]) + visioncraft__cli->>visioncraft__cli: error(70, #quot;invalid Git …) + Note over visioncraft__cli: return Err(error(70, #quot;invalid Git object identifier#quot;)) + end + visioncraft__cli->>visioncraft__cli: git(root, &_, cancelled)? + opt via map_err + visioncraft__cli->>visioncraft__cli: error(70, #quot;invalid comm…) + end + opt !size.success ||!declared.bytes().all(| b | b.is_asc… + visioncraft__cli->>visioncraft__cli: error(70, #quot;committed bl…) + Note over visioncraft__cli: return Err(error(70, #quot;committed blob size is unavailabl… + end + opt via map_err + visioncraft__cli->>visioncraft__cli: error(70, #quot;invalid comm…) + end + opt declared> MAX_FILE + visioncraft__cli->>visioncraft__cli: error(2, #quot;committed so…) + Note over visioncraft__cli: return Err(error(2, #quot;committed source blob exceeds insp… + end + visioncraft__cli->>visioncraft__cli: git(root, &_, cancelled)? + opt !blob.success || blob.stdout.len() as u64 != declared + visioncraft__cli->>visioncraft__cli: error(70, #quot;committed so…) + Note over visioncraft__cli: return Err(error(70, #quot;committed source blob is unavaila… + end + visioncraft__cli->>visioncraft: crate::sha256(&blob.stdout) + visioncraft__cli->>visioncraft__cli: confined(root, path, false) + alt Ok(file) + visioncraft__cli->>visioncraft__cli: read_bounded(&file, MAX_FILE)? + else Err(_) if !root.join(path).try_exists().map_err(io_erro… + Note over visioncraft__cli: return Ok(true) + else Err(e) + Note over visioncraft__cli: return Err(e) + end + visioncraft__cli->>visioncraft: crate::sha256(¤t) + opt committed_hash != crate::sha256(¤t) + Note over visioncraft__cli: return Ok(true) + end + end +``` + +## `sym:cargo visioncraft . cli/inputs().` +`fn inputs(root: &Path, paths: &[String], missing_ok: bool) -> Result, CliError>` · L506-L534 +```mermaid +sequenceDiagram + participant visioncraft__cli as cli mod + participant visioncraft as visioncraft mod + loop for path in paths + visioncraft__cli->>visioncraft__cli: confined(root, path, false) + alt Ok(file) + visioncraft__cli->>visioncraft__cli: read_bounded(&file, MAX_FILE)? + visioncraft__cli->>visioncraft: crate::sha256(&_) + else Err(_) if missing_ok && !root.join(path).try_exists().m… + loop for c in Path::new(path).components() + alt Err(e) + visioncraft__cli->>visioncraft__cli: io_error(e) + Note over visioncraft__cli: return Err(io_error(e)) + else Ok(m) if m.file_type().is_symlink() + visioncraft__cli->>visioncraft__cli: error(2, #quot;symlinked in…) + Note over visioncraft__cli: return Err(error(2, #quot;symlinked input refused#quot;)) + end + end + else Err(e) + Note over visioncraft__cli: return Err(e) + end + end +``` + +## `sym:cargo visioncraft . cli/source_snapshot().` +`fn source_snapshot(root: &Path, paths: &[String], revision: &str, expected: &[Artifact],) -> Result, CliError>` · L536-L570 +```mermaid +sequenceDiagram + participant visioncraft__cli as cli mod + participant visioncraft as visioncraft mod + participant _sealmap_corpus as sealmap_corpus ext + loop for path in paths + visioncraft__cli->>visioncraft__cli: confined(root, path, false)? + visioncraft__cli->>visioncraft__cli: read_bounded(&_, MAX_JSON)? + opt total>(MAX_JSON / 5) as usize + visioncraft__cli->>visioncraft__cli: error(2, #quot;dirty select…) + Note over visioncraft__cli: return Err(error(2, #quot;dirty selected inputs exceed priva… + end + visioncraft__cli->>visioncraft: crate::sha256(&bytes) + visioncraft__cli->>_sealmap_corpus: Artifact::iter() + opt !expected.iter().any(| a | &a.path == path && a.sha2… + visioncraft__cli->>visioncraft__cli: error(1, #quot;selected inp…) + Note over visioncraft__cli: return Err(error(1, #quot;selected inputs changed while capt… + end + end + visioncraft__cli->>visioncraft__cli: json_bytes(&_) +``` + +## `sym:cargo visioncraft . cli/init().` +`fn init(options: InitOptions, cancelled: &AtomicBool) -> Result` · L577-L665 +```mermaid +sequenceDiagram + participant visioncraft__cli as cli mod + participant visioncraft as visioncraft mod + participant visioncraft__plan___tQualityPlan as QualityPlan + participant visioncraft__process as process mod + visioncraft__cli->>visioncraft__cli: root(&options.root)? + visioncraft__cli->>visioncraft__cli: output_path(&options.out)? + opt paths.windows(2).any(| p | p [0] == p [1]) + visioncraft__cli->>visioncraft__cli: error(2, #quot;input paths …) + Note over visioncraft__cli: return Err(error(2, #quot;input paths must be unique#quot;)) + end + loop for path in &paths + visioncraft__cli->>visioncraft: crate::relative_path(path) + opt !crate::relative_path(path) + visioncraft__cli->>visioncraft__cli: error(2, #quot;input paths …) + Note over visioncraft__cli: return Err(error(2, #quot;input paths must be relative#quot;)) + end + end + visioncraft__cli->>visioncraft__cli: revision(&root, cancelled)? + visioncraft__cli->>visioncraft__cli: inputs(&root, &paths, false)? + visioncraft__cli->>visioncraft__cli: selected_dirty(&root, &paths, cancelled)? + opt dirty + visioncraft__cli->>visioncraft__cli: source_snapshot(&root, &paths, &revision, &selected)? + end + opt via ok_or_else + visioncraft__cli->>visioncraft__cli: error(2, #quot;plan filenam…) + end + opt via map + visioncraft__cli->>visioncraft: crate::sha256(bytes) + end + visioncraft__cli->>visioncraft__plan___tQualityPlan: validate() + visioncraft__cli->>visioncraft__cli: confined(&root, &_.invocation.cwd, true)? + visioncraft__cli->>visioncraft__cli: inputs(&root, &paths, false)? + opt inputs(&root, &paths, false)? != plan.subject.inputs + visioncraft__cli->>visioncraft__cli: error(1, #quot;selected inp…) + Note over visioncraft__cli: return Err(error(1, #quot;selected inputs changed while prep… + end + opt let Some(bytes) = &snapshot + opt via ok_or_else + visioncraft__cli->>visioncraft__cli: error(2, #quot;plan needs p…) + end + visioncraft__cli->>visioncraft__process: process::private_directory(&snapshot_root) + visioncraft__cli->>visioncraft__cli: write_new(&join(), b#quot;*\n#quot;)? + visioncraft__cli->>visioncraft__cli: write_new(&snapshot_path, bytes)? + end + visioncraft__cli->>visioncraft__cli: json_bytes(&plan)? + visioncraft__cli->>visioncraft__cli: write_new(&out, &_)? + visioncraft__cli->>visioncraft__cli: print_json(&_)? +``` + +## `sym:cargo visioncraft . cli/add_artifact().` +`fn add_artifact(verified: &mut VerifiedArtifacts, root: &Path, artifact: &Artifact,) -> Result<(), CliError>` · L667-L675 +```mermaid +sequenceDiagram + participant visioncraft__cli as cli mod + participant visioncraft as visioncraft mod + participant visioncraft__evidence___tVerifiedArtifacts as VerifiedArtifacts + visioncraft__cli->>visioncraft: crate::artifact_shape(artifact) + visioncraft__cli->>visioncraft__cli: confined(root, &artifact.path, false)? + visioncraft__cli->>visioncraft__cli: read_bounded(&_, MAX_FILE)? + visioncraft__cli->>visioncraft__evidence___tVerifiedArtifacts: insert(artifact, &bytes) +``` + +## `sym:cargo visioncraft . cli/evidence_parent().` +`fn evidence_parent(root: &Path, path: &str) -> Result` · L687-L698 +```mermaid +sequenceDiagram + participant visioncraft__cli as cli mod + participant visioncraft as visioncraft mod + participant visioncraft__process as process mod + visioncraft__cli->>visioncraft: crate::relative_path(path) + opt !crate::relative_path(path) + visioncraft__cli->>visioncraft__cli: error(2, #quot;artifact out…) + Note over visioncraft__cli: return Err(error(2, #quot;artifact output path is not confin… + end + opt let Some(parent) = path.parent() + opt !parent.exists() + visioncraft__cli->>visioncraft__process: process::private_directory(parent) + end + end + visioncraft__cli->>visioncraft__cli: output_path(&path) +``` + +## `sym:cargo visioncraft . cli/run().` +`fn run(options: RunOptions, cancelled: &AtomicBool) -> Result` · L772-L928 +```mermaid +sequenceDiagram + participant visioncraft__cli as cli mod + participant visioncraft as visioncraft mod + participant visioncraft__process as process mod + participant visioncraft__plan___tQualityPlan as QualityPlan + participant visioncraft__evidence___tExecutionReceipt as ExecutionReceipt + visioncraft__cli->>visioncraft__cli: root(&options.root)? + visioncraft__cli->>visioncraft__cli: read_plan(&options.plan)? + opt selected.is_empty() + visioncraft__cli->>visioncraft__cli: error(2, #quot;selected che…) + Note over visioncraft__cli: return Err(error(2, #quot;selected check does not exist#quot;)) + end + loop for check in &selected + opt !matches!(check.evaluator, Evaluator::ExitCode {..}) + visioncraft__cli->>visioncraft__cli: error(78, #quot;reported eva…) + Note over visioncraft__cli: return Err(error(78, #quot;reported evaluators require their… + end + visioncraft__cli->>visioncraft__cli: confined(&source_root, &check.invocation.cwd, true)? + end + visioncraft__cli->>visioncraft__cli: revision(&source_root, cancelled)? + visioncraft__cli->>visioncraft__cli: inputs(&source_root, &paths, false)? + opt revision(&source_root, cancelled)? != plan.subject.r… + visioncraft__cli->>visioncraft__cli: error(1, #quot;current sele…) + Note over visioncraft__cli: return Err(error(1, #quot;current selected source does not m… + end + opt let Some(snapshot) = &plan.subject.working_tree + visioncraft__cli->>visioncraft__cli: confined(&plan_root, &snapshot.path, false)? + visioncraft__cli->>visioncraft__cli: read_bounded(&_, MAX_JSON)? + visioncraft__cli->>visioncraft: crate::sha256(&bytes) + opt crate::sha256(&bytes) != snapshot.sha256 + visioncraft__cli->>visioncraft__cli: error(2, #quot;dirty snapsh…) + Note over visioncraft__cli: return Err(error(2, #quot;dirty snapshot hash does not match… + end + end + visioncraft__cli->>visioncraft__process: process::private_directory(&options.out) + visioncraft__cli->>visioncraft__cli: root(&options.out)? + visioncraft__cli->>visioncraft__cli: write_new(&join(), b#quot;*\n#quot;)? + visioncraft__cli->>visioncraft__cli: json_bytes(&plan)? + visioncraft__cli->>visioncraft__cli: write_new(&join(), &_)? + opt let (Some(snapshot), Some(bytes)) = (&plan.subject.w… + visioncraft__cli->>visioncraft__cli: evidence_parent(&out, &snapshot.path)? + visioncraft__cli->>visioncraft__cli: write_new(&_, &bytes)? + end + loop for (index, check) in selected.into_iter().enumerate() + visioncraft__cli->>visioncraft__cli: inputs(&source_root, &paths, false)? + visioncraft__cli->>visioncraft__cli: revision(&source_root, cancelled)? + opt inputs(&source_root, &paths, false)? != plan.subject… + visioncraft__cli->>visioncraft__cli: error(1, #quot;selected inp…) + Note over visioncraft__cli: return Err(error(1, #quot;selected inputs changed before a l… + end + visioncraft__cli->>visioncraft__cli: confined(&source_root, &check.invocation.cwd, true)? + visioncraft__cli->>visioncraft__process: process::private_directory(&attempt) + visioncraft__cli->>visioncraft__cli: executable(&check.invocation, &source_root) + opt resolved.as_ref().is_some_and(| path | path.to_str()… + visioncraft__cli->>visioncraft__cli: error(78, #quot;resolved exe…) + Note over visioncraft__cli: return Err(error(78, #quot;resolved executable path is not r… + end + opt via and_then + visioncraft__cli->>visioncraft__cli: read_bounded(path, MAX_FILE) + end + opt via map + visioncraft__cli->>visioncraft: crate::sha256(&bytes) + end + visioncraft__cli->>visioncraft__process: process::run_command(&actual_invocation, &source_root, … + visioncraft__cli->>visioncraft__cli: read_bounded(&captured.stdout, MAX_FILE)? + visioncraft__cli->>visioncraft: crate::sha256(&_) + visioncraft__cli->>visioncraft__cli: read_bounded(&captured.stderr, MAX_FILE)? + visioncraft__cli->>visioncraft: crate::sha256(&_) + visioncraft__cli->>visioncraft__cli: process_status(captured.termination) + visioncraft__cli->>visioncraft__cli: inputs(&source_root, &paths, true) + visioncraft__cli->>visioncraft__plan___tQualityPlan: ~digest() + visioncraft__cli->>visioncraft__evidence___tExecutionReceipt: validate() + visioncraft__cli->>visioncraft__cli: json_bytes(&receipt)? + visioncraft__cli->>visioncraft__cli: write_new(&path, &_)? + visioncraft__cli->>visioncraft__cli: execution_exit(&receipt, &check.evaluator) + end + visioncraft__cli->>visioncraft__cli: print_json(&_)? +``` + +## `sym:cargo visioncraft . cli/load_receipts().` +`fn load_receipts(directory: &Path, verified: &mut VerifiedArtifacts,) -> Result, CliError>` · L930-L960 +```mermaid +sequenceDiagram + participant visioncraft__cli as cli mod + participant visioncraft__evidence___tExecutionReceipt as ExecutionReceipt + visioncraft__cli->>visioncraft__cli: root(directory)? + loop for entry in fs::read_dir(&root).map_err(io_error)? + opt metadata.file_type().is_symlink() + visioncraft__cli->>visioncraft__cli: error(2, #quot;symlinked en…) + Note over visioncraft__cli: return Err(error(2, #quot;symlinked entries in run evidence … + end + opt name.starts_with(#quot;check-#quot;) && metadata.is_dir() + visioncraft__cli->>visioncraft__cli: confined(&root, &_, false)? + end + end + loop for path in paths + visioncraft__cli->>visioncraft__cli: read_bounded(&path, MAX_JSON)? + visioncraft__cli->>visioncraft__evidence___tExecutionReceipt: ExecutionReceipt::parse(&_) + visioncraft__cli->>visioncraft__cli: receipt_artifacts(&receipt) + loop for artifact in receipt_artifacts(&receipt) + visioncraft__cli->>visioncraft__cli: add_artifact(verified, &root, artifact)? + end + end +``` + +## `sym:cargo visioncraft . cli/evaluate_options().` +`fn evaluate_options(options: EvaluateOptions, cancelled: &AtomicBool) -> Result` · L962-L1089 +```mermaid +sequenceDiagram + participant visioncraft__cli as cli mod + participant visioncraft as visioncraft mod + participant visioncraft__plan___tSubject as Subject + participant visioncraft__evidence___tVerifiedArtifacts as VerifiedArtifacts + participant visioncraft__cli___tContextFile as ContextFile + participant visioncraft__evaluate___tEvaluationContext as EvaluationContext + participant _sealmap_corpus as sealmap_corpus ext + participant visioncraft__evaluate as evaluate mod + visioncraft__cli->>visioncraft__cli: root(&options.root)? + visioncraft__cli->>visioncraft__cli: read_plan(&options.plan)? + visioncraft__cli->>visioncraft__cli: revision(&source_root, cancelled)? + visioncraft__cli->>visioncraft__cli: inputs(&source_root, &paths, true)? + opt current.inputs.is_empty() + visioncraft__cli->>visioncraft__cli: error(1, #quot;all selected…) + Note over visioncraft__cli: return Err(error(1, #quot;all selected source inputs are mis… + end + visioncraft__cli->>visioncraft__cli: selected_dirty(&source_root, &paths, cancelled)? + opt current.dirty + visioncraft__cli->>visioncraft__cli: json_bytes(¤t.inputs)? + visioncraft__cli->>visioncraft: crate::sha256(&_) + end + opt let Some(path) = &options.current_subject + visioncraft__cli->>visioncraft__cli: read_explicit(path, MAX_JSON)? + visioncraft__cli->>visioncraft: crate::from_json(&bytes) + visioncraft__cli->>visioncraft__plan___tSubject: validate() + opt supplied.repository != current.repository || supplie… + visioncraft__cli->>visioncraft__cli: error(2, #quot;supplied cur…) + Note over visioncraft__cli: return Err(error(2, #quot;supplied current subject contradic… + end + end + visioncraft__cli->>visioncraft__evidence___tVerifiedArtifacts: ~VerifiedArtifacts::default() + loop for directory in &options.receipts + visioncraft__cli->>visioncraft__cli: load_receipts(directory, &verified)? + end + visioncraft__cli->>visioncraft__cli___tContextFile: ~ContextFile::default() + opt let Some(path) = &options.context + visioncraft__cli->>visioncraft__cli: read_explicit(path, MAX_JSON)? + visioncraft__cli->>visioncraft: crate::from_json(&bytes) + loop for artifact in context_data.audits.iter().map(| a | &a… + visioncraft__cli->>visioncraft__cli: add_artifact(&verified, &context_root, artifact)? + end + end + visioncraft__cli->>visioncraft__cli: git(&source_root, &_, cancelled)? + visioncraft__cli->>visioncraft__evaluate___tEvaluationContext: EvaluationContext::new(unwrap_or_else(), ¤t, &ver… + loop for declaration in context_data.families + opt !aliases.insert(declaration.route.clone()) + visioncraft__cli->>visioncraft__cli: error(2, #quot;duplicate mo…) + Note over visioncraft__cli: return Err(error(2, #quot;duplicate model-family declaration… + end + visioncraft__cli->>_sealmap_corpus: Family::named(&declaration.family) + end + visioncraft__cli->>visioncraft__evaluate: crate::evaluate(&plan, &receipts, &context) + opt options.json + visioncraft__cli->>visioncraft__cli: print_json(&report)? + end +``` + +## `sym:cargo visioncraft . cli/execute().` +`pub fn execute(cli: Cli, cancelled: &AtomicBool) -> Result` · L1091-L1130 +> Dispatch an explicit CLI operation. +```mermaid +sequenceDiagram + participant visioncraft__cli as cli mod + participant visioncraft__deepsec as deepsec mod + alt Operation::Plan { command: PlanCommand::Init(options), } + visioncraft__cli->>visioncraft__cli: init(_, cancelled) + else Operation::Plan { command: PlanCommand::Check { plan, j… + visioncraft__cli->>visioncraft__cli: read_plan(&plan)? + opt json + visioncraft__cli->>visioncraft__cli: print_json(&_)? + end + else Operation::Run(options) + visioncraft__cli->>visioncraft__cli: run(options, cancelled) + else Operation::Evaluate(options) | Operation::Gate { comman… + visioncraft__cli->>visioncraft__cli: evaluate_options(options, cancelled) + else Operation::Deepsec(options) + visioncraft__cli->>visioncraft__deepsec: deepsec::execute(&options, cancelled) + opt via map_err + visioncraft__cli->>visioncraft__cli: error(e.code, e.message) + end + end +``` diff --git a/docs/diagrams/generated/src/deepsec.rs.md b/docs/diagrams/generated/src/deepsec.rs.md new file mode 100644 index 0000000..40a480e --- /dev/null +++ b/docs/diagrams/generated/src/deepsec.rs.md @@ -0,0 +1,376 @@ +--- +sealmap: 2 +source: src/deepsec.rs +module: "sym:cargo visioncraft . deepsec/" +language: rust +source_hash: blake3:fe5f7e3e8985a7eeb253589267c66d64771af816b56d031e6022a81c9b5649ae +lines: 1013 +fragments: 5 +--- +# `sym:cargo visioncraft . deepsec/` · src/deepsec.rs +> Executed Deepsec 2.3.10 gates with explicit policy and retained error states. + +## structure +```mermaid +classDiagram + direction LR + class visioncraft__deepsec___tDeepsecOptions["DeepsecOptions"] { + <> + +diff: Option#lt;String#gt; + +diff_working: bool + +diff_staged: bool + +files_from: Option#lt;PathBuf#gt; + +full: bool + +scan_only: bool + +root: Option#lt;PathBuf#gt; + +report_dir: Option#lt;PathBuf#gt; + +policy_json: Option#lt;String#gt; + +fail_on: Option#lt;String#gt; + +thinking_level: Option#lt;String#gt; + +agent: Option#lt;String#gt; + +model: Option#lt;String#gt; + +model_auth: Option#lt;String#gt; + +dry_run: bool + } + class visioncraft__deepsec___tDeepsecPolicy["DeepsecPolicy"] { + <> + +enabled: bool + +agent: String + +model_auth: String + +model: String + +thinking_level: String + +fail_on: String + +max_duration: String + +batch_size: u32 + +concurrency: u32 + +ai_provider: String + +ai_api_key_env: String + +ai_base_url: String + +policy_source: String + +max_output_bytes: u64 + +Default::default() Self + +validate(&self) Result#lt;u64, GateError#gt; + } + class visioncraft__deepsec___tGateError["GateError"] { + <> + +code: i32 + +message: String + } + class visioncraft__deepsec___tStrictJson["StrictJson"] { + <> + -0: Value + +Deserialize#lt;'de#gt;::deserialize(deserializer: D) Result#lt;Self, D::Error#gt; + } + class visioncraft__deepsec["visioncraft::deepsec"] { + <> + +execute(options: &DeepsecOptions, cancelled: &AtomicBool) Result#lt;i32, GateError#gt; + } + class _serde__Deserialize["serde::Deserialize"] { + <> + } + visioncraft__deepsec ..> visioncraft__deepsec___tDeepsecOptions + visioncraft__deepsec ..> visioncraft__deepsec___tGateError + visioncraft__deepsec___tDeepsecPolicy ..> visioncraft__deepsec___tGateError + visioncraft__deepsec___tStrictJson ..|> _serde__Deserialize +``` + +## `sym:cargo visioncraft . deepsec/DeepsecPolicy#validate().` +`pub fn validate(&self) -> Result` · L142-L229 +> Validate policy and return the whole-attempt deadline in milliseconds. +```mermaid +sequenceDiagram + participant visioncraft__deepsec___tDeepsecPolicy as DeepsecPolicy + participant visioncraft__deepsec as deepsec mod + participant _url as url ext + opt ![#quot;claude#quot;, #quot;codex#quot;, #quot;pi#quot;].contains(&self.agent.as_s… + visioncraft__deepsec___tDeepsecPolicy->>visioncraft__deepsec: error(78, #quot;unsupported …) + Note over visioncraft__deepsec___tDeepsecPolicy: return Err(error(78, #quot;unsupported Deepsec agent#quot;)) + end + opt ![#quot;local#quot;, #quot;direct#quot;, #quot;custom#quot;].contains(&self.model_… + visioncraft__deepsec___tDeepsecPolicy->>visioncraft__deepsec: error(78, #quot;unsupported …) + Note over visioncraft__deepsec___tDeepsecPolicy: return Err(error(78, #quot;unsupported model authentication … + end + opt ![#quot;minimal#quot;, #quot;low#quot;, #quot;medium#quot;, #quot;high#quot;, #quot;xhigh#quot;].conta… + visioncraft__deepsec___tDeepsecPolicy->>visioncraft__deepsec: error(78, #quot;unsupported …) + Note over visioncraft__deepsec___tDeepsecPolicy: return Err(error(78, #quot;unsupported thinking level#quot;)) + end + opt !SEVERITIES.contains(&self.fail_on.as_str()) + visioncraft__deepsec___tDeepsecPolicy->>visioncraft__deepsec: error(78, #quot;unsupported …) + Note over visioncraft__deepsec___tDeepsecPolicy: return Err(error(78, #quot;unsupported severity threshold#quot;)) + end + opt !(1..= 100).contains(&self.batch_size) ||!(1..= 32).… + visioncraft__deepsec___tDeepsecPolicy->>visioncraft__deepsec: error(78, #quot;invalid batc…) + Note over visioncraft__deepsec___tDeepsecPolicy: return Err(error(78, #quot;invalid batch, concurrency or out… + end + opt [&self.model, &self.policy_source, &self.ai_provider… + visioncraft__deepsec___tDeepsecPolicy->>visioncraft__deepsec: error(78, #quot;invalid poli…) + Note over visioncraft__deepsec___tDeepsecPolicy: return Err(error(78, #quot;invalid policy string#quot;)) + end + opt !self.ai_api_key_env.is_empty() && !(self.ai_api_key… + visioncraft__deepsec___tDeepsecPolicy->>visioncraft__deepsec: error(78, #quot;invalid cred…) + Note over visioncraft__deepsec___tDeepsecPolicy: return Err(error(78, #quot;invalid credential environment na… + end + opt !self.ai_base_url.is_empty() + visioncraft__deepsec___tDeepsecPolicy->>_url: Url::parse(&self.ai_base_url) + opt via map_err + visioncraft__deepsec___tDeepsecPolicy->>visioncraft__deepsec: error(78, #quot;invalid mode…) + end + opt ![#quot;http#quot;, #quot;https#quot;].contains(&url.scheme()) || url.ho… + visioncraft__deepsec___tDeepsecPolicy->>visioncraft__deepsec: error(78, #quot;base URL mus…) + Note over visioncraft__deepsec___tDeepsecPolicy: return Err(error(78, #quot;base URL must be HTTP(S), without… + end + end + alt #quot;local#quot; if self.agent == #quot;pi#quot; + visioncraft__deepsec___tDeepsecPolicy->>visioncraft__deepsec: error(78, #quot;local authen…) + Note over visioncraft__deepsec___tDeepsecPolicy: return Err(error(78, #quot;local authentication requires cla… + else #quot;direct#quot; if ![#quot;anthropic#quot;, #quot;openai#quot;].contains(&self.ai_… + visioncraft__deepsec___tDeepsecPolicy->>visioncraft__deepsec: error(78, #quot;direct authe…) + Note over visioncraft__deepsec___tDeepsecPolicy: return Err(error(78, #quot;direct authentication requires a … + else #quot;custom#quot; if self.agent != #quot;pi#quot; || self.ai_api_key_env.i… + visioncraft__deepsec___tDeepsecPolicy->>visioncraft__deepsec: error(78, #quot;custom authe…) + Note over visioncraft__deepsec___tDeepsecPolicy: return Err(error(78, #quot;custom authentication requires pi… + end + visioncraft__deepsec___tDeepsecPolicy->>visioncraft__deepsec: duration_ms(&self.max_duration) + opt via ok_or_else + visioncraft__deepsec___tDeepsecPolicy->>visioncraft__deepsec: error(78, #quot;invalid dura…) + end +``` + +## `sym:cargo visioncraft . deepsec/findings().` +`fn findings(bytes: &[u8]) -> Result, GateError>` · L371-L410 +```mermaid +sequenceDiagram + participant visioncraft__deepsec as deepsec mod + participant _serde_json as serde_json ext + visioncraft__deepsec->>_serde_json: serde_json::from_slice(bytes) + opt via map_err + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;malformed or…) + end + opt via ok_or_else + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;unrecognised…) + end + loop for row in rows + alt if let Some(nested) = row.get(#quot;findings#quot;).and_then(Valu… + loop for finding in nested + opt via ok_or_else + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;finding must…) + end + end + else + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;unrecognised…) + Note over visioncraft__deepsec: return Err(error(70, #quot;unrecognised finding row#quot;)) + end + end + loop for finding in &mut output + opt via ok_or_else + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;finding lack…) + end + opt !SEVERITIES.contains(&severity.as_str()) + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;finding has …) + Note over visioncraft__deepsec: return Err(error(70, #quot;finding has an unrecognised sever… + end + end +``` + +## `sym:cargo visioncraft . deepsec/Attempt#command().` +`fn command(&mut self, stage: &str, program: &str, args: Vec, cwd: &Path, model: bool, stdin: bool,) -> Result<(i32, Vec), GateError>` · L484-L548 +```mermaid +sequenceDiagram + participant visioncraft__deepsec___tAttempt as Attempt + participant visioncraft__deepsec as deepsec mod + participant visioncraft__process as process mod + participant _serde_json as serde_json ext + opt via ok_or_else + visioncraft__deepsec___tAttempt->>visioncraft__deepsec: error(124, #quot;whole-attemp…) + end + visioncraft__deepsec___tAttempt->>visioncraft__process: private_directory(&directory) + visioncraft__deepsec___tAttempt->>visioncraft__deepsec: environment(self.policy, model) + visioncraft__deepsec___tAttempt->>_serde_json: serde_json::to_vec_pretty(&invocation) + opt via map_err + visioncraft__deepsec___tAttempt->>visioncraft__deepsec: error(70, #quot;invocation s…) + end + visioncraft__deepsec___tAttempt->>visioncraft__deepsec: write_new(&join(), &_)? + visioncraft__deepsec___tAttempt->>visioncraft__process: run_command(&invocation, cwd, &directory, self.cancelle… + visioncraft__deepsec___tAttempt->>visioncraft__deepsec: read_bounded(&run.stdout, self.policy.max_output_bytes)? + visioncraft__deepsec___tAttempt->>visioncraft__deepsec: read_bounded(&run.stderr, self.policy.max_output_bytes)? + visioncraft__deepsec___tAttempt->>_serde_json: serde_json::to_vec_pretty(&execution) + opt via map_err + visioncraft__deepsec___tAttempt->>visioncraft__deepsec: error(70, #quot;execution se…) + end + visioncraft__deepsec___tAttempt->>visioncraft__deepsec: write_new(&join(), &_)? + alt Termination::Completed if run.signal.is_none() + opt via ok_or_else + visioncraft__deepsec___tAttempt->>visioncraft__deepsec: error(70, #quot;missing exit…) + end + else Termination::Unavailable + visioncraft__deepsec___tAttempt->>visioncraft__deepsec: error(78, #quot;required exe…) + else Termination::TimedOut + visioncraft__deepsec___tAttempt->>visioncraft__deepsec: error(124, #quot;whole-attemp…) + else Termination::Interrupted + visioncraft__deepsec___tAttempt->>visioncraft__deepsec: error(130, #quot;review inter…) + else _ + visioncraft__deepsec___tAttempt->>visioncraft__deepsec: error(70, #quot;review proce…) + end +``` + +## `sym:cargo visioncraft . deepsec/execute().` +`pub fn execute(options: &DeepsecOptions, cancelled: &AtomicBool) -> Result` · L571-L975 +> Execute an explicitly requested security gate, returning its legacy exit code. +```mermaid +sequenceDiagram + participant visioncraft__deepsec as deepsec mod + participant visioncraft as visioncraft mod + participant visioncraft__deepsec___tDeepsecPolicy as DeepsecPolicy + participant _serde_json as serde_json ext + participant visioncraft__process as process mod + participant _tempfile as tempfile ext + participant visioncraft__deepsec___tAttempt as Attempt + participant _recorded as recorded ext + opt modes.into_iter().filter(| x | * x).count() != 1 || … + visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;choose exact…) + Note over visioncraft__deepsec: return Err(error(78, #quot;choose exactly one nonempty sourc… + end + visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;Deepsec proc…) + alt Some(text) + visioncraft__deepsec->>visioncraft: from_json(as_bytes()) + opt via map_err + visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;invalid poli…) + end + else None + visioncraft__deepsec->>visioncraft__deepsec___tDeepsecPolicy: DeepsecPolicy::default() + end + opt !policy.enabled + visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;Deepsec gate…) + Note over visioncraft__deepsec: return Err(error(78, #quot;Deepsec gate disabled by policy#59; … + end + visioncraft__deepsec->>visioncraft__deepsec: root_for(options)? + opt Some(path) + opt via map_err + visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;file manifes…) + end + visioncraft__deepsec->>visioncraft__deepsec: read_bounded(&path, _) + opt via map_err + visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;file manifes…) + end + end + opt options.dry_run + visioncraft__deepsec->>_serde_json: serde_json::to_string_pretty(&plan) + opt via map_err + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;plan seriali…) + end + Note over visioncraft__deepsec: return Ok(0) + end + opt !options.scan_only && policy.model_auth != #quot;local#quot; &… + visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;configured c…) + Note over visioncraft__deepsec: return Err(error(78, #quot;configured credential environment… + end + alt Ok(_) + visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;review works…) + Note over visioncraft__deepsec: return Err(error(78, #quot;review workspace must be an ordin… + else Err(e) if e.kind() == std::io::ErrorKind::NotFound + visioncraft__deepsec->>visioncraft__process: private_directory(&workspace) + else Err(_) + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;review works…) + Note over visioncraft__deepsec: return Err(error(70, #quot;review workspace unavailable#quot;)) + end + visioncraft__deepsec->>visioncraft__deepsec: workspace_lock(&workspace)? + opt fs::symlink_metadata(&report).is_ok() + visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;report direc…) + Note over visioncraft__deepsec: return Err(error(78, #quot;report directory must be new#quot;)) + end + visioncraft__deepsec->>visioncraft__process: private_directory(&report) + visioncraft__deepsec->>visioncraft__process: private_file(&join()) + visioncraft__deepsec->>_serde_json: serde_json::to_vec_pretty(&plan) + opt via map_err + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;plan seriali…) + end + visioncraft__deepsec->>visioncraft__deepsec: write_new(&join(), &_)? + opt !workspace.join(#quot;.gitignore#quot;).exists() + visioncraft__deepsec->>visioncraft__deepsec: write_new(&join(), b#quot;*\n#quot;)? + end + opt fs::symlink_metadata(&config).is_ok_and(| m |!m.is_f… + visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;configuratio…) + Note over visioncraft__deepsec: return Err(error(78, #quot;configuration path is not an ordi… + end + visioncraft__deepsec->>_serde_json: serde_json::to_string_pretty(&config_value) + opt via map_err + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;configuratio…) + end + visioncraft__deepsec->>_tempfile: NamedTempFile::new_in(&workspace) + opt via map_err + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;cannot final…) + end + opt closure + visioncraft__deepsec->>visioncraft__deepsec___tAttempt: command(#quot;version#quot;, #quot;deepsec#quot;, _, &workspace, false, fal…? + visioncraft__deepsec->>visioncraft__deepsec: supported_version() + opt rc != 0 || version_text != supported_version() + visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;Deepsec vers…) + Note over visioncraft__deepsec: return Err(error(78, #quot;Deepsec version does not match th… + end + visioncraft__deepsec->>visioncraft__deepsec___tAttempt: command(#quot;revision#quot;, #quot;git#quot;, _, &root, false, false)? + visioncraft__deepsec->>visioncraft__deepsec___tAttempt: command(#quot;dirty#quot;, #quot;git#quot;, _, &root, false, false)? + visioncraft__deepsec->>_recorded: recorded::select(options, as_deref(), &attempt, &root)? + visioncraft__deepsec->>_recorded: recorded::snapshot(&root, &selected)? + visioncraft__deepsec->>_serde_json: serde_json::to_vec_pretty(&before) + opt via map_err + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;source encod…) + end + visioncraft__deepsec->>visioncraft__deepsec: write_new(&join(), &_)? + visioncraft__deepsec->>visioncraft__deepsec: write_new(&source_list, as_bytes())? + opt options.scan_only || options.full + visioncraft__deepsec->>visioncraft__deepsec___tAttempt: command(#quot;scan#quot;, #quot;deepsec#quot;, args, &workspace, false, fal…? + opt rc != 0 + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;Deepsec scan…) + Note over visioncraft__deepsec: return Err(error(70, #quot;Deepsec scan failed#quot;)) + end + opt options.scan_only + Note over visioncraft__deepsec: return Ok(json!({ #quot;result#quot;: #quot;SCANNED#quot;, #quot;deepsec_exit#quot;: … + end + end + opt options.full + visioncraft__deepsec->>_recorded: recorded::pending(&data, &before)? + end + visioncraft__deepsec->>_recorded: recorded::run_files(&data)? + visioncraft__deepsec->>visioncraft__deepsec___tAttempt: command(#quot;process#quot;, #quot;deepsec#quot;, args, &workspace, true, f…? + opt (options.full && rc != 0) || (!options.full && ![0, … + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;Deepsec proc…) + Note over visioncraft__deepsec: return Err(error(70, #quot;Deepsec processing failed#quot;)) + end + visioncraft__deepsec->>visioncraft__deepsec: read_bounded(&join(), policy.max_output_bytes) + opt rc == 1 && read_bounded(&report.join(#quot;comment.md#quot;), … + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;exit 1 witho…) + Note over visioncraft__deepsec: return Err(error(70, #quot;exit 1 without fresh completed fi… + end + visioncraft__deepsec->>_recorded: recorded::snapshot(&root, &selected)? + visioncraft__deepsec->>_serde_json: serde_json::to_vec_pretty(&after) + opt via map_err + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;source encod…) + end + visioncraft__deepsec->>visioncraft__deepsec: write_new(&join(), &_)? + opt before != after + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;review input…) + Note over visioncraft__deepsec: return Err(error(70, #quot;review inputs changed while the r… + end + visioncraft__deepsec->>_recorded: recorded::validate_review(&data, &prior_runs, &expected…? + visioncraft__deepsec->>visioncraft__deepsec___tAttempt: command(#quot;export#quot;, #quot;deepsec#quot;, args, &workspace, false, f…? + opt export_rc != 0 + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;Deepsec find…) + Note over visioncraft__deepsec: return Err(error(70, #quot;Deepsec findings export failed#quot;)) + end + visioncraft__deepsec->>visioncraft__deepsec: read_bounded(&join(), policy.max_output_bytes)? + visioncraft__deepsec->>visioncraft__deepsec: findings(&raw)? + opt rc == 1 && findings.is_empty() + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;findings exi…) + Note over visioncraft__deepsec: return Err(error(70, #quot;findings exit with an empty expor… + end + end + visioncraft__deepsec->>_serde_json: serde_json::to_vec_pretty(&receipt) + opt via map_err + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;receipt enco…) + end + visioncraft__deepsec->>visioncraft__deepsec: write_new(&join(), &_)? + visioncraft__deepsec->>_serde_json: serde_json::to_string_pretty(&receipt) + opt via map_err + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;receipt enco…) + end +``` diff --git a/docs/diagrams/generated/src/deepsec_evidence.rs.md b/docs/diagrams/generated/src/deepsec_evidence.rs.md new file mode 100644 index 0000000..429d9d5 --- /dev/null +++ b/docs/diagrams/generated/src/deepsec_evidence.rs.md @@ -0,0 +1,234 @@ +--- +sealmap: 2 +source: src/deepsec_evidence.rs +module: "sym:cargo visioncraft . deepsec_evidence/" +language: rust +source_hash: blake3:7bdca6b97bbbee14a261123c7f4f1a363cf86abefbaf059141d6e3f8985a36d2 +lines: 317 +fragments: 6 +--- +# `sym:cargo visioncraft . deepsec_evidence/` · src/deepsec_evidence.rs +> Private checks against the pinned reviewer's persisted protocol. + +## structure +```mermaid +classDiagram + direction LR + class visioncraft__deepsec_evidence["visioncraft::deepsec_evidence"] { + <> + #pending(super) Result#lt;Vec#lt;Artifact#gt;, GateError#gt; + #run_files(super) Result#lt;BTreeSet#lt;String#gt;, GateError#gt; + #select(super) Result#lt;Vec#lt;String#gt;, GateError#gt; + #snapshot(super) Result#lt;Vec#lt;Artifact#gt;, GateError#gt; + #validate_review(super) Result#lt;Value, GateError#gt; + } + class _sealmap_corpus__review__Artifact["sealmap_corpus::review::Artifact"] { + <> + } + class _serde_json__Value["serde_json::Value"] { + <> + } + class _visioncraft__Attempt["visioncraft::Attempt"] { + <> + } + class _visioncraft__DeepsecOptions["visioncraft::DeepsecOptions"] { + <> + } + class _visioncraft__GateError["visioncraft::GateError"] { + <> + } + visioncraft__deepsec_evidence ..> _sealmap_corpus__review__Artifact + visioncraft__deepsec_evidence ..> _serde_json__Value + visioncraft__deepsec_evidence ..> _visioncraft__Attempt + visioncraft__deepsec_evidence ..> _visioncraft__DeepsecOptions + visioncraft__deepsec_evidence ..> _visioncraft__GateError +``` + +## `sym:cargo visioncraft . deepsec_evidence/confined().` +`fn confined(root: &Path, relative: &str) -> Result` · L15-L37 +```mermaid +sequenceDiagram + participant visioncraft__deepsec_evidence as deepsec_evidence mod + participant visioncraft as visioncraft mod + participant _visioncraft as visioncraft ext + visioncraft__deepsec_evidence->>visioncraft: crate::relative_path(relative) + opt !crate::relative_path(relative) || relative.trim() !… + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;source path …) + Note over visioncraft__deepsec_evidence: return Err(error(78, #quot;source path cannot be represented… + end + loop for part in Path::new(relative).components() + opt via map_err + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;review sourc…) + end + opt fs::symlink_metadata(&path).map_err(| _ | error(70, … + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;review sourc…) + Note over visioncraft__deepsec_evidence: return Err(error(78, #quot;review source must not traverse s… + end + end +``` + +## `sym:cargo visioncraft . deepsec_evidence/snapshot().` +`pub(super) fn snapshot(root: &Path, paths: &[String]) -> Result, GateError>` · L38-L60 +```mermaid +sequenceDiagram + participant visioncraft__deepsec_evidence as deepsec_evidence mod + participant _visioncraft as visioncraft ext + participant visioncraft as visioncraft mod + opt paths.len()> 100_000 + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;review file …) + Note over visioncraft__deepsec_evidence: return Err(error(78, #quot;review file count exceeds 100000#quot;… + end + opt via map + visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: confined(root, name)? + visioncraft__deepsec_evidence->>_visioncraft: ~read_bounded(&_, _)? + opt total> 256 * 1024 * 1024 + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;review sourc…) + Note over visioncraft__deepsec_evidence: return Err(error(78, #quot;review source exceeds 256 MiB#59; ch… + end + visioncraft__deepsec_evidence->>visioncraft: sha256(&bytes) + end +``` + +## `sym:cargo visioncraft . deepsec_evidence/select().` +`pub(super) fn select(options: &DeepsecOptions, files: Option<&Path>, attempt: &mut Attempt<'_>, root: &Path,) -> Result, GateError>` · L61-L169 +```mermaid +sequenceDiagram + participant visioncraft__deepsec_evidence as deepsec_evidence mod + participant _visioncraft as visioncraft ext + alt let Some(files) = files + alt files == Path::new(#quot;-#quot;) + opt rc != 0 + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;could not re…) + Note over visioncraft__deepsec_evidence: return Err(error(78, #quot;could not read file list#quot;)) + end + else + visioncraft__deepsec_evidence->>_visioncraft: ~read_bounded(files, _)? + end + else + opt let Some(reference) = &options.diff + opt reference.starts_with('-') + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;diff referen…) + Note over visioncraft__deepsec_evidence: return Err(error(78, #quot;diff reference must not be a Git … + end + end + opt rc != 0 + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;could not re…) + Note over visioncraft__deepsec_evidence: return Err(error(78, #quot;could not resolve review source s… + end + opt options.diff_working + opt rc != 0 + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;could not re…) + Note over visioncraft__deepsec_evidence: return Err(error(78, #quot;could not resolve untracked selec… + end + end + end + opt via map_err + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;file list mu…) + end + opt paths.is_empty() + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;no review in…) + Note over visioncraft__deepsec_evidence: return Err(error(78, #quot;no review inputs#59; this is not a c… + end + loop for path in &paths + visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: confined(root, path)? + end + opt options.diff_staged + opt via map_err + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;Git paths mu…) + end + opt rc != 0 || changed.split('\0').any(| p | paths.conta… + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;staged input…) + Note over visioncraft__deepsec_evidence: return Err(error(78, #quot;staged inputs differ from working… + end + end +``` + +## `sym:cargo visioncraft . deepsec_evidence/run_files().` +`pub(super) fn run_files(data: &Path) -> Result, GateError>` · L170-L193 +```mermaid +sequenceDiagram + participant visioncraft__deepsec_evidence as deepsec_evidence mod + participant _visioncraft as visioncraft ext + opt !dir.exists() + Note over visioncraft__deepsec_evidence: return Ok(BTreeSet::new()) + end + opt via map_err + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;review run d…) + end + opt !meta.is_dir() || meta.file_type().is_symlink() + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;invalid revi…) + Note over visioncraft__deepsec_evidence: return Err(error(70, #quot;invalid review run directory#quot;)) + end + opt via map_err + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;review runs …) + end + loop for item in fs::read_dir(dir).map_err(| _ | error(70, #quot;… + opt via map_err + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;review run e…) + end + opt set.len()>= 100_000 + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;review histo…) + Note over visioncraft__deepsec_evidence: return Err(error(70, #quot;review history exceeds limit#quot;)) + end + end +``` + +## `sym:cargo visioncraft . deepsec_evidence/validate_review().` +`pub(super) fn validate_review(data: &Path, prior: &BTreeSet, expected: &[Artifact], root: &Path, project: &str, report: &Path,) -> Result` · L220-L317 +```mermaid +sequenceDiagram + participant visioncraft__deepsec_evidence as deepsec_evidence mod + participant _sealmap_corpus as sealmap_corpus ext + participant _serde_json as serde_json ext + participant _visioncraft as visioncraft ext + participant visioncraft as visioncraft mod + visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: run_files(data)? + loop for name in run_files(data)?.difference(prior) + visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: object(&join())? + end + visioncraft__deepsec_evidence->>_sealmap_corpus: Artifact::iter() + opt via map + visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: file_record(data, &artifact.path) + end + visioncraft__deepsec_evidence->>_serde_json: serde_json::to_vec_pretty(&evidence) + opt via map_err + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;review evide…) + end + visioncraft__deepsec_evidence->>_visioncraft: ~write_new(&join(), &bytes)? + opt runs.len() != 1 + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;missing or a…) + Note over visioncraft__deepsec_evidence: return Err(error(70, #quot;missing or ambiguous fresh proces… + end + loop each via filter + visioncraft__deepsec_evidence->>visioncraft: crate::identifier(s) + end + opt via ok_or_else + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;invalid proc…) + end + visioncraft__deepsec_evidence->>_sealmap_corpus: Artifact::len() + opt run [#quot;phase#quot;] != #quot;done#quot; || run [#quot;projectId#quot;] != proj… + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;processing r…) + Note over visioncraft__deepsec_evidence: return Err(error(70, #quot;processing run is incomplete or c… + end + loop for artifact in expected + opt record [#quot;filePath#quot;] != artifact.path || record [#quot;pro… + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;review file …) + Note over visioncraft__deepsec_evidence: return Err(error(70, #quot;review file identity, content or … + end + opt via ok_or_else + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;missing per-…) + end + opt entries.len() != 1 + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;missing or a…) + Note over visioncraft__deepsec_evidence: return Err(error(70, #quot;missing or ambiguous analysis for… + end + opt entry [#quot;refusal#quot;] [#quot;refused#quot;].as_bool() != Some(fals… + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;review was r…) + Note over visioncraft__deepsec_evidence: return Err(error(70, #quot;review was refused, partly skippe… + end + opt entry [#quot;usage#quot;] [#quot;outputTokens#quot;].as_u64().is_none_or… + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;review lacks…) + Note over visioncraft__deepsec_evidence: return Err(error(70, #quot;review lacks actual model identit… + end + end +``` diff --git a/docs/diagrams/generated/src/evaluate.rs.md b/docs/diagrams/generated/src/evaluate.rs.md new file mode 100644 index 0000000..acddb6f --- /dev/null +++ b/docs/diagrams/generated/src/evaluate.rs.md @@ -0,0 +1,234 @@ +--- +sealmap: 2 +source: src/evaluate.rs +module: "sym:cargo visioncraft . evaluate/" +language: rust +source_hash: blake3:e2b3c4721974ba40222309382bfb4dc2a311296e18b7324982cd29215db905a1 +lines: 658 +fragments: 4 +--- +# `sym:cargo visioncraft . evaluate/` · src/evaluate.rs +> Read-only evaluation of explicit plans, exact receipts and supplied context. + +## structure +```mermaid +classDiagram + direction LR + class visioncraft__evaluate___tCheckOutcome["CheckOutcome"] { + <> + Passed + Blocked + Skipped + Inconclusive + Error + } + class visioncraft__evaluate___tCheckReport["CheckReport"] { + <> + +id: String + +required: bool + +attempt_id: Option#lt;String#gt; + +outcome: CheckOutcome + +reasons: Vec#lt;String#gt; + } + class visioncraft__evaluate___tEvaluationContext["EvaluationContext#lt;'a#gt;"] { + <> + +now_ms: u64 + +current_subject: &'a Subject + +verified: &'a VerifiedArtifacts + +ancestor_revisions: &'a [String] + +families: FamilyCatalogue + +audits: &'a [AuditReceipt] + +manual_observations: &'a [ManualObservation] + +new(now_ms: u64, current_subject: &'a Subject, verified: &'a VerifiedArtifacts) Self + } + class visioncraft__evaluate___tExpectationReport["ExpectationReport"] { + <> + +id: String + +required: bool + +outcome: CheckOutcome + +reasons: Vec#lt;String#gt; + } + class visioncraft__evaluate___tGateOutcome["GateOutcome"] { + <> + Passed + Blocked + Incomplete + Error + } + class visioncraft__evaluate___tGateReport["GateReport"] { + <> + +outcome: GateOutcome + +required_checks: usize + +passed_required_checks: usize + +checks: Vec#lt;CheckReport#gt; + +expectations: Vec#lt;ExpectationReport#gt; + +errors: Vec#lt;String#gt; + +passed(&self) bool + } + class visioncraft__evaluate["visioncraft::evaluate"] { + <> + +evaluate(plan: &QualityPlan, receipts: &[ExecutionReceipt], context: &EvaluationContext#lt;'_#gt;,) GateReport + } + class visioncraft__evidence___tExecutionReceipt["ExecutionReceipt"] { + <> + } + class visioncraft__plan___tQualityPlan["QualityPlan"] { + <> + } + class visioncraft__evidence___tAuditReceipt["AuditReceipt"] { + <> + } + class visioncraft__evidence___tManualObservation["ManualObservation"] { + <> + } + class visioncraft__evidence___tVerifiedArtifacts["VerifiedArtifacts"] { + <> + } + class visioncraft__plan___tSubject["Subject"] { + <> + } + class _sealmap_corpus__route__FamilyCatalogue["sealmap_corpus::route::FamilyCatalogue"] { + <> + } + visioncraft__evaluate ..> visioncraft__evaluate___tEvaluationContext + visioncraft__evaluate ..> visioncraft__evaluate___tGateReport + visioncraft__evaluate ..> visioncraft__evidence___tExecutionReceipt + visioncraft__evaluate ..> visioncraft__plan___tQualityPlan + visioncraft__evaluate___tCheckReport *-- visioncraft__evaluate___tCheckOutcome : outcome + visioncraft__evaluate___tEvaluationContext o-- visioncraft__evidence___tAuditReceipt : audits + visioncraft__evaluate___tEvaluationContext o-- visioncraft__evidence___tManualObservation : manual_observations + visioncraft__evaluate___tEvaluationContext o-- visioncraft__evidence___tVerifiedArtifacts : verified + visioncraft__evaluate___tEvaluationContext o-- visioncraft__plan___tSubject : current_subject + visioncraft__evaluate___tEvaluationContext *-- _sealmap_corpus__route__FamilyCatalogue : families + visioncraft__evaluate___tExpectationReport *-- visioncraft__evaluate___tCheckOutcome : outcome + visioncraft__evaluate___tGateReport o-- visioncraft__evaluate___tCheckReport : checks + visioncraft__evaluate___tGateReport o-- visioncraft__evaluate___tExpectationReport : expectations + visioncraft__evaluate___tGateReport *-- visioncraft__evaluate___tGateOutcome : outcome +``` + +## `sym:cargo visioncraft . evaluate/check_receipt().` +`fn check_receipt(plan: &QualityPlan, digest: &str, check: &crate::CheckSpec, receipt: &ExecutionReceipt, context: &EvaluationContext<'_>,) -> (CheckOutcome, Vec)` · L160-L273 +```mermaid +sequenceDiagram + participant visioncraft__evaluate as evaluate mod + participant visioncraft__evidence___tExecutionReceipt as ExecutionReceipt + participant visioncraft__plan as plan mod + participant visioncraft__evidence___tVerifiedArtifacts as VerifiedArtifacts + visioncraft__evaluate->>visioncraft__evidence___tExecutionReceipt: validate() + opt let Err(e) = receipt.validate() + Note over visioncraft__evaluate: return error(&e.to_string()) + end + opt receipt.plan_sha256 != digest || receipt.subject != … + Note over visioncraft__evaluate: return error(#quot;receipt plan, subject or invocation does … + end + visioncraft__evaluate->>visioncraft__plan: same_inputs(&receipt.subject.inputs, &receipt.inputs_af… + opt !same_inputs(&receipt.subject.inputs, &receipt.input… + Note over visioncraft__evaluate: return (CheckOutcome::Inconclusive, vec![#quot;selected inpu… + end + visioncraft__evaluate->>visioncraft__evaluate: context_limits(plan, context) + visioncraft__evaluate->>visioncraft__evaluate: age_limit(receipt.finished_at_ms, plan, context) + opt !limits.is_empty() + Note over visioncraft__evaluate: return (CheckOutcome::Inconclusive, limits) + end + opt receipt.process != ProcessStatus::Completed + Note over visioncraft__evaluate: return (outcome, vec![receipt.diagnostic.clone().unwrap… + end + opt receipt.elapsed_ms> check.invocation.timeout_ms + Note over visioncraft__evaluate: return error(#quot;completed execution exceeded the configur… + end + loop for output in receipt.stdout.iter().chain(receipt.stder… + visioncraft__evaluate->>visioncraft__evidence___tVerifiedArtifacts: ~byte_len(output) + alt let Some(bytes) = context.verified.byte_len(output) + opt let-else + Note over visioncraft__evaluate: return error(#quot;output length overflow#quot;) + end + else + Note over visioncraft__evaluate: return error(#quot;raw output artifact has not been byte-ver… + end + end + opt output_bytes> check.invocation.max_output_bytes + Note over visioncraft__evaluate: return error(#quot;verified raw output exceeds configured ca… + end + opt let Some(snapshot) = &receipt.subject.working_tree + opt !context.verified.contains(snapshot) + Note over visioncraft__evaluate: return error(#quot;dirty working-tree snapshot has not been … + end + end + alt Some(paths) if !check.scope.iter().all(| p | paths.cont… + Note over visioncraft__evaluate: return (CheckOutcome::Inconclusive, vec![#quot;observed scop… + else None if plan.policy.require_observed_scope + Note over visioncraft__evaluate: return (CheckOutcome::Inconclusive, vec![#quot;observed sour… + end + alt Evaluator::ExitCode { success_codes } + opt receipt.reported.is_some() + Note over visioncraft__evaluate: return error(#quot;unexpected adapter assessment for an exit… + end + else Evaluator::Reported { adapter } + opt let-else + Note over visioncraft__evaluate: return error(#quot;missing required adapter assessment#quot;) + end + opt &result.adapter != adapter ||!context.verified.conta… + Note over visioncraft__evaluate: return error(#quot;adapter identity or verified report artif… + end + end +``` + +## `sym:cargo visioncraft . evaluate/assessment_binding().` +`fn assessment_binding(plan: &QualityPlan, digest: &str, subject: &Subject, claimed: &str, artifact: &crate::Artifact, at: u64, context: &EvaluationContext<'_>,) -> Result<(), ContractError>` · L298-L320 +```mermaid +sequenceDiagram + participant visioncraft__evaluate as evaluate mod + participant visioncraft as visioncraft mod + visioncraft__evaluate->>visioncraft: crate::require(_, #quot;assessment p…)? + visioncraft__evaluate->>visioncraft: artifact_shape(artifact)? + visioncraft__evaluate->>visioncraft: crate::require(contains(), #quot;assessment a…)? + visioncraft__evaluate->>visioncraft__evaluate: age_limit(at, plan, context) + visioncraft__evaluate->>visioncraft: crate::require(is_none(), #quot;assessment i…) +``` + +## `sym:cargo visioncraft . evaluate/expectation_report().` +`fn expectation_report(plan: &QualityPlan, digest: &str, expectation: &Expectation, checks: &[CheckReport], runs: &BTreeMap<&str, &ExecutionReceipt>, context: &EvaluationContext<'_>,) -> ExpectationRe…` · L322-L524 +```mermaid +sequenceDiagram + participant visioncraft__evaluate as evaluate mod + participant visioncraft as visioncraft mod + participant _sealmap_corpus as sealmap_corpus ext + loop for id in &expectation.checks + visioncraft__evaluate->>visioncraft__evaluate: referenced_check(id, checks, &reasons, &outcome) + end + opt let Some(control) = &expectation.positive_control + visioncraft__evaluate->>visioncraft__evaluate: referenced_check(control, checks, &reasons, &outcome) + end + opt let Some(stabilizer) = &expectation.stabilizer + visioncraft__evaluate->>visioncraft__evaluate: referenced_check(&stabilizer.check_id, checks, &reasons… + end + opt expectation.independent_audit || context.audits.iter… + opt not audits.len() != 1 + opt closure + visioncraft__evaluate->>visioncraft__evaluate: assessment_binding(plan, digest, &a.subject, &a.plan_sh…? + visioncraft__evaluate->>visioncraft: nonempty(&a.observed) + visioncraft__evaluate->>visioncraft: identifier(&a.producer.agent_id) + visioncraft__evaluate->>visioncraft: identifier(&a.reviewer.agent_id) + visioncraft__evaluate->>visioncraft: crate::require(_, #quot;audit must i…)? + visioncraft__evaluate->>visioncraft: crate::require(_, #quot;audit actors…)? + visioncraft__evaluate->>visioncraft: crate::require(any(), #quot;producer doe…)? + visioncraft__evaluate->>visioncraft: crate::require(_, #quot;audit requir…)? + visioncraft__evaluate->>visioncraft: crate::require(is_some_and(), #quot;reviewer doe…)? + visioncraft__evaluate->>visioncraft: crate::require(any(), #quot;adversarial …)? + opt expectation.independent_audit + visioncraft__evaluate->>_sealmap_corpus: route::cross_family_with(&a.producer.model, &a.reviewer… + end + end + end + end + opt expectation.category == EvidenceCategory::Manual || … + opt not observations.len() != 1 + visioncraft__evaluate->>visioncraft__evaluate: assessment_binding(plan, digest, &m.subject, &m.plan_sh… + opt via and_then + visioncraft__evaluate->>visioncraft: nonempty(&m.observer) + visioncraft__evaluate->>visioncraft: nonempty(&m.observed) + visioncraft__evaluate->>visioncraft: crate::require(_, #quot;manual obser…) + end + end + end +``` diff --git a/docs/diagrams/generated/src/evidence.rs.md b/docs/diagrams/generated/src/evidence.rs.md new file mode 100644 index 0000000..ea454b8 --- /dev/null +++ b/docs/diagrams/generated/src/evidence.rs.md @@ -0,0 +1,194 @@ +--- +sealmap: 2 +source: src/evidence.rs +module: "sym:cargo visioncraft . evidence/" +language: rust +source_hash: blake3:edfe990a885f2bcad685855fe0c87e11878174d676e4414f4f9448e818ca520a +lines: 292 +fragments: 2 +--- +# `sym:cargo visioncraft . evidence/` · src/evidence.rs +> Immutable run and audit records, with caller-supplied byte verification. + +## structure +```mermaid +classDiagram + direction LR + class visioncraft__evidence___tActor["Actor"] { + <> + +agent_id: String + +attempt_id: String + +model: String + } + class visioncraft__evidence___tAuditReceipt["AuditReceipt"] { + <> + +expectation_id: String + +plan_sha256: String + +subject: Subject + +producer: Actor + +reviewer: Actor + +probe_check: String + +verdict: AuditVerdict + +observed: String + +artifact: Artifact + +captured_at_ms: u64 + } + class visioncraft__evidence___tAuditVerdict["AuditVerdict"] { + <> + Supported + Contradicted + Inconclusive + } + class visioncraft__evidence___tExecutionReceipt["ExecutionReceipt"] { + <> + +version: u32 + +attempt_id: String + +plan_sha256: String + +check_id: String + +subject: Subject + +invocation: Invocation + +executable: String + +executable_sha256: Option#lt;String#gt; + +tool_version: Option#lt;String#gt; + +started_at_ms: u64 + +finished_at_ms: u64 + +elapsed_ms: u64 + +process: ProcessStatus + +exit_code: Option#lt;i32#gt; + +signal: Option#lt;i32#gt; + +capture_complete: bool + +stdout: Option#lt;Artifact#gt; + +stderr: Option#lt;Artifact#gt; + +inputs_after: Vec#lt;Artifact#gt; + +observed_scope: Option#lt;Vec#lt;String#gt;#gt; + +observed_tests: Vec#lt;String#gt; + +reported: Option#lt;ReportedResult#gt; + +diagnostic: Option#lt;String#gt; + +parse(bytes: &[u8]) Result#lt;Self, ContractError#gt; + +validate(&self) Result#lt;#40;#41;, ContractError#gt; + } + class visioncraft__evidence___tManualObservation["ManualObservation"] { + <> + +expectation_id: String + +plan_sha256: String + +subject: Subject + +observer: String + +observed: String + +verdict: AuditVerdict + +artifact: Artifact + +captured_at_ms: u64 + } + class visioncraft__evidence___tProcessStatus["ProcessStatus"] { + <> + Completed + Unavailable + TimedOut + Interrupted + FailedToStart + CaptureFailed + } + class visioncraft__evidence___tReportedResult["ReportedResult"] { + <> + +adapter: String + +outcome: CheckOutcome + +reason: String + +artifact: Artifact + } + class visioncraft__evidence___tVerifiedArtifacts["VerifiedArtifacts"] { + <> + -entries: BTreeMap#lt;#40;String, String#41;, u64#gt; + +byte_len(&self, artifact: &Artifact) Option#lt;u64#gt; + +contains(&self, artifact: &Artifact) bool + +insert(&mut self, artifact: &Artifact, bytes: &[u8]) Result#lt;#40;#41;, ContractError#gt; + } + class visioncraft__plan___tSubject["Subject"] { + <> + } + class _sealmap_corpus__review__Artifact["sealmap_corpus::review::Artifact"] { + <> + } + class visioncraft___tContractError["ContractError"] { + <> + } + class visioncraft__plan___tInvocation["Invocation"] { + <> + } + class visioncraft__evaluate___tCheckOutcome["CheckOutcome"] { + <> + } + visioncraft__evidence___tAuditReceipt *-- visioncraft__evidence___tActor : producer, reviewer + visioncraft__evidence___tAuditReceipt *-- visioncraft__evidence___tAuditVerdict : verdict + visioncraft__evidence___tAuditReceipt *-- visioncraft__plan___tSubject : subject + visioncraft__evidence___tAuditReceipt *-- _sealmap_corpus__review__Artifact : artifact + visioncraft__evidence___tExecutionReceipt ..> visioncraft___tContractError + visioncraft__evidence___tExecutionReceipt *-- visioncraft__evidence___tProcessStatus : process + visioncraft__evidence___tExecutionReceipt o-- visioncraft__evidence___tReportedResult : reported + visioncraft__evidence___tExecutionReceipt *-- visioncraft__plan___tInvocation : invocation + visioncraft__evidence___tExecutionReceipt *-- visioncraft__plan___tSubject : subject + visioncraft__evidence___tExecutionReceipt o-- _sealmap_corpus__review__Artifact : stdout, stderr, inputs_after + visioncraft__evidence___tManualObservation *-- visioncraft__evidence___tAuditVerdict : verdict + visioncraft__evidence___tManualObservation *-- visioncraft__plan___tSubject : subject + visioncraft__evidence___tManualObservation *-- _sealmap_corpus__review__Artifact : artifact + visioncraft__evidence___tReportedResult *-- visioncraft__evaluate___tCheckOutcome : outcome + visioncraft__evidence___tReportedResult *-- _sealmap_corpus__review__Artifact : artifact + visioncraft__evidence___tVerifiedArtifacts ..> visioncraft___tContractError + visioncraft__evidence___tVerifiedArtifacts ..> _sealmap_corpus__review__Artifact +``` + +## `sym:cargo visioncraft . evidence/ExecutionReceipt#validate().` +`pub fn validate(&self) -> Result<(), ContractError>` · L107-L178 +> Check receipt consistency; matching a plan and bytes is a separate step. +```mermaid +sequenceDiagram + participant visioncraft__evidence___tExecutionReceipt as ExecutionReceipt + participant visioncraft as visioncraft mod + participant visioncraft__plan___tSubject as Subject + participant visioncraft__plan___tInvocation as Invocation + participant visioncraft__plan as plan mod + visioncraft__evidence___tExecutionReceipt->>visioncraft: require(_, #quot;unsupported …)? + visioncraft__evidence___tExecutionReceipt->>visioncraft: identifier(&self.attempt_id) + visioncraft__evidence___tExecutionReceipt->>visioncraft: identifier(&self.check_id) + visioncraft__evidence___tExecutionReceipt->>visioncraft: require(_, #quot;invalid rece…)? + visioncraft__evidence___tExecutionReceipt->>visioncraft: hex(&self.plan_sha256, &_) + visioncraft__evidence___tExecutionReceipt->>visioncraft: require(hex(), #quot;invalid plan…)? + visioncraft__evidence___tExecutionReceipt->>visioncraft__plan___tSubject: validate()? + visioncraft__evidence___tExecutionReceipt->>visioncraft__plan___tInvocation: validate()? + visioncraft__evidence___tExecutionReceipt->>visioncraft: nonempty(&self.executable) + visioncraft__evidence___tExecutionReceipt->>visioncraft: require(nonempty(), #quot;executable i…)? + opt let Some(hash) = &self.executable_sha256 + visioncraft__evidence___tExecutionReceipt->>visioncraft: hex(hash, &_) + visioncraft__evidence___tExecutionReceipt->>visioncraft: require(hex(), #quot;invalid exec…)? + end + opt let Some(version) = &self.tool_version + visioncraft__evidence___tExecutionReceipt->>visioncraft: nonempty(version) + visioncraft__evidence___tExecutionReceipt->>visioncraft: require(nonempty(), #quot;empty tool v…)? + end + visioncraft__evidence___tExecutionReceipt->>visioncraft: require(_, #quot;finish prece…)? + visioncraft__evidence___tExecutionReceipt->>visioncraft: require(_, #quot;exit code an…)? + alt self.process == ProcessStatus::Completed + visioncraft__evidence___tExecutionReceipt->>visioncraft: require(_, #quot;completed ex…)? + visioncraft__evidence___tExecutionReceipt->>visioncraft: require(_, #quot;completed ex…)? + else + visioncraft__evidence___tExecutionReceipt->>visioncraft: require(is_some_and(), #quot;incomplete e…)? + end + loop for a in self.stdout.iter().chain(self.stderr.iter()) + visioncraft__evidence___tExecutionReceipt->>visioncraft: artifact_shape(a)? + end + visioncraft__evidence___tExecutionReceipt->>visioncraft__plan: validate_input_paths(&self.inputs_after)? + opt let Some(paths) = &self.observed_scope + loop each via all + visioncraft__evidence___tExecutionReceipt->>visioncraft: crate::relative_path(p) + end + visioncraft__evidence___tExecutionReceipt->>visioncraft: require(_, #quot;invalid or d…)? + end + loop each via all + visioncraft__evidence___tExecutionReceipt->>visioncraft: nonempty(t) + end + visioncraft__evidence___tExecutionReceipt->>visioncraft: require(_, #quot;invalid or d…)? + opt let Some(reported) = &self.reported + visioncraft__evidence___tExecutionReceipt->>visioncraft: identifier(&reported.adapter) + visioncraft__evidence___tExecutionReceipt->>visioncraft: nonempty(&reported.reason) + visioncraft__evidence___tExecutionReceipt->>visioncraft: require(_, #quot;reported ass…)? + visioncraft__evidence___tExecutionReceipt->>visioncraft: artifact_shape(&reported.artifact)? + end +``` diff --git a/docs/diagrams/generated/src/lib.rs.md b/docs/diagrams/generated/src/lib.rs.md new file mode 100644 index 0000000..18511d1 --- /dev/null +++ b/docs/diagrams/generated/src/lib.rs.md @@ -0,0 +1,45 @@ +--- +sealmap: 2 +source: src/lib.rs +module: "sym:cargo visioncraft ." +language: rust +source_hash: blake3:337326f4db730b3c5a5b0457e94f425a596bc8dd6d765e3e51bc9d78bc56b9ad +lines: 129 +fragments: 1 +--- +# `sym:cargo visioncraft .` · src/lib.rs +> Explicit quality contracts, without implicit execution or claims of correctness. + +## structure +```mermaid +classDiagram + direction LR + class visioncraft___tContractError["ContractError"] { + <> + Json#123; line: usize, column: usize, #125; + Invalid#40;String#41; + } + class visioncraft { + <> + ~artifact_shape(crate) Result#lt;#40;#41;, ContractError#gt; + +mod cli + +mod deepsec + +mod deepsec_evidence + +mod evaluate + +mod evidence + +from_json(bytes: &[u8]) Result#lt;T, ContractError#gt; + ~hex(crate) bool + ~identifier(crate) bool + ~nonempty(crate) bool + +mod plan + +mod process + ~relative_path(crate) bool + ~require(crate) Result#lt;#40;#41;, ContractError#gt; + +sha256(bytes: &[u8]) String + } + class _sealmap_corpus__review__Artifact["sealmap_corpus::review::Artifact"] { + <> + } + visioncraft ..> visioncraft___tContractError + visioncraft ..> _sealmap_corpus__review__Artifact +``` diff --git a/docs/diagrams/generated/src/main.rs.md b/docs/diagrams/generated/src/main.rs.md new file mode 100644 index 0000000..9c33e65 --- /dev/null +++ b/docs/diagrams/generated/src/main.rs.md @@ -0,0 +1,20 @@ +--- +sealmap: 2 +source: src/main.rs +module: "sym:cargo visioncraft_main ." +language: rust +source_hash: blake3:99d2860c356b50b40860a89032581ec5c2ae5c16e89fca73d9a59be073f78872 +lines: 38 +fragments: 1 +--- +# `sym:cargo visioncraft_main .` · src/main.rs +> VisionCraft's explicit command-line entry point and cancellation bridge. + +## structure +```mermaid +classDiagram + direction LR + class visioncraft_main { + <> + } +``` diff --git a/docs/diagrams/generated/src/plan.rs.md b/docs/diagrams/generated/src/plan.rs.md new file mode 100644 index 0000000..1fe62cb --- /dev/null +++ b/docs/diagrams/generated/src/plan.rs.md @@ -0,0 +1,212 @@ +--- +sealmap: 2 +source: src/plan.rs +module: "sym:cargo visioncraft . plan/" +language: rust +source_hash: blake3:a0eaf6b6e34139a3b02ddc3d521d69dc4c064884b96dfe85585b1a1e7da2107d +lines: 413 +fragments: 4 +--- +# `sym:cargo visioncraft . plan/` · src/plan.rs +> Typed plans describe explicitly selected checks; parsing never runs them. + +## structure +```mermaid +classDiagram + direction LR + class visioncraft__plan___tCheckSpec["CheckSpec"] { + <> + +id: String + +required: bool + +invocation: Invocation + +evaluator: Evaluator + +scope: Vec#lt;String#gt; + } + class visioncraft__plan___tEvaluator["Evaluator"] { + <> + ExitCode#123; success_codes: Vec#lt;i32#gt;, #125; + Reported#123; adapter: String, #125; + } + class visioncraft__plan___tEvidenceCategory["EvidenceCategory"] { + <> + Executable + PartiallyVerifiable + Manual + } + class visioncraft__plan___tExpectation["Expectation"] { + <> + +id: String + +claim: String + +required: bool + +category: EvidenceCategory + +checks: Vec#lt;String#gt; + +regression_critical: bool + +stabilizer: Option#lt;Stabilizer#gt; + +positive_control: Option#lt;String#gt; + +independent_audit: bool + +limitation: Option#lt;String#gt; + } + class visioncraft__plan___tGatePolicy["GatePolicy"] { + <> + +max_age_ms: Option#lt;u64#gt; + +require_observed_scope: bool + } + class visioncraft__plan___tInvocation["Invocation"] { + <> + +program: String + +args: Vec#lt;String#gt; + +cwd: String + +env: Vec#lt;String#gt; + +timeout_ms: u64 + +max_output_bytes: u64 + +validate(&self) Result#lt;#40;#41;, ContractError#gt; + } + class visioncraft__plan___tQualityPlan["QualityPlan"] { + <> + +version: u32 + +id: String + +subject: Subject + +checks: Vec#lt;CheckSpec#gt; + +expectations: Vec#lt;Expectation#gt; + +policy: GatePolicy + +digest(&self) Result#lt;String, ContractError#gt; + +parse(bytes: &[u8]) Result#lt;Self, ContractError#gt; + +validate(&self) Result#lt;#40;#41;, ContractError#gt; + } + class visioncraft__plan___tStabilizer["Stabilizer"] { + <> + +check_id: String + +test_id: String + } + class visioncraft__plan___tSubject["Subject"] { + <> + +repository: String + +revision: String + +configuration: String + +dirty: bool + +working_tree: Option#lt;Artifact#gt; + +inputs: Vec#lt;Artifact#gt; + +validate(&self) Result#lt;#40;#41;, ContractError#gt; + } + class visioncraft__plan["visioncraft::plan"] { + <> + +const MAX_PLAN_CHECKS: usize + +const MAX_PLAN_DURATION_MS: u64 + +const MAX_PLAN_OUTPUT_BYTES: u64 + ~same_inputs(crate) bool + ~validate_input_paths(crate) Result#lt;#40;#41;, ContractError#gt; + ~validate_inputs(crate) Result#lt;#40;#41;, ContractError#gt; + } + class visioncraft___tContractError["ContractError"] { + <> + } + class _sealmap_corpus__review__Artifact["sealmap_corpus::review::Artifact"] { + <> + } + visioncraft__plan ..> visioncraft___tContractError + visioncraft__plan ..> _sealmap_corpus__review__Artifact + visioncraft__plan___tCheckSpec *-- visioncraft__plan___tEvaluator : evaluator + visioncraft__plan___tCheckSpec *-- visioncraft__plan___tInvocation : invocation + visioncraft__plan___tExpectation *-- visioncraft__plan___tEvidenceCategory : category + visioncraft__plan___tExpectation o-- visioncraft__plan___tStabilizer : stabilizer + visioncraft__plan___tInvocation ..> visioncraft___tContractError + visioncraft__plan___tQualityPlan ..> visioncraft___tContractError + visioncraft__plan___tQualityPlan o-- visioncraft__plan___tCheckSpec : checks + visioncraft__plan___tQualityPlan o-- visioncraft__plan___tExpectation : expectations + visioncraft__plan___tQualityPlan *-- visioncraft__plan___tGatePolicy : policy + visioncraft__plan___tQualityPlan *-- visioncraft__plan___tSubject : subject + visioncraft__plan___tSubject ..> visioncraft___tContractError + visioncraft__plan___tSubject o-- _sealmap_corpus__review__Artifact : working_tree, inputs +``` + +## `sym:cargo visioncraft . plan/Subject#validate().` +`pub fn validate(&self) -> Result<(), ContractError>` · L36-L58 +> Check identity, dirty-snapshot and unique input-path requirements. +```mermaid +sequenceDiagram + participant visioncraft__plan___tSubject as Subject + participant visioncraft as visioncraft mod + participant visioncraft__plan as plan mod + visioncraft__plan___tSubject->>visioncraft: nonempty(&self.repository) + visioncraft__plan___tSubject->>visioncraft: require(nonempty(), #quot;subject.repo…)? + visioncraft__plan___tSubject->>visioncraft: hex(&self.revision, &_) + visioncraft__plan___tSubject->>visioncraft: require(hex(), #quot;subject.revi…)? + visioncraft__plan___tSubject->>visioncraft: nonempty(&self.configuration) + visioncraft__plan___tSubject->>visioncraft: require(nonempty(), #quot;subject.conf…)? + visioncraft__plan___tSubject->>visioncraft: require(_, #quot;dirty subjec…)? + opt let Some(a) = &self.working_tree + visioncraft__plan___tSubject->>visioncraft: artifact_shape(a)? + end + visioncraft__plan___tSubject->>visioncraft__plan: validate_inputs(&self.inputs) +``` + +## `sym:cargo visioncraft . plan/Invocation#validate().` +`pub fn validate(&self) -> Result<(), ContractError>` · L104-L137 +> Validate the bounded argv contract without resolving executables or env. +```mermaid +sequenceDiagram + participant visioncraft__plan___tInvocation as Invocation + participant visioncraft as visioncraft mod + visioncraft__plan___tInvocation->>visioncraft: nonempty(&self.program) + visioncraft__plan___tInvocation->>visioncraft: require(nonempty(), #quot;invocation.p…)? + visioncraft__plan___tInvocation->>visioncraft: require(all(), #quot;argv cannot …)? + visioncraft__plan___tInvocation->>visioncraft: relative_path(&self.cwd) + visioncraft__plan___tInvocation->>visioncraft: require(_, #quot;cwd must be …)? + loop for name in &self.env + visioncraft__plan___tInvocation->>visioncraft: require(_, #quot;invalid envi…)? + visioncraft__plan___tInvocation->>visioncraft: require(insert(), #quot;duplicate en…)? + end + visioncraft__plan___tInvocation->>visioncraft: require(contains(), #quot;timeout_ms o…)? + visioncraft__plan___tInvocation->>visioncraft: require(contains(), #quot;max_output_b…) +``` + +## `sym:cargo visioncraft . plan/QualityPlan#validate().` +`pub fn validate(&self) -> Result<(), ContractError>` · L291-L398 +> Validate identifiers, references and bounded execution policies. +```mermaid +sequenceDiagram + participant visioncraft__plan___tQualityPlan as QualityPlan + participant visioncraft as visioncraft mod + participant visioncraft__plan___tSubject as Subject + visioncraft__plan___tQualityPlan->>visioncraft: require(_, #quot;unsupported …)? + visioncraft__plan___tQualityPlan->>visioncraft: require(_, #quot;plan check c…)? + visioncraft__plan___tQualityPlan->>visioncraft: identifier(&self.id) + visioncraft__plan___tQualityPlan->>visioncraft: require(identifier(), #quot;invalid plan…)? + visioncraft__plan___tQualityPlan->>visioncraft__plan___tSubject: validate()? + visioncraft__plan___tQualityPlan->>visioncraft: require(_, #quot;a gate requi…)? + visioncraft__plan___tQualityPlan->>visioncraft: require(_, #quot;max_age_ms m…)? + loop for c in &self.checks + visioncraft__plan___tQualityPlan->>visioncraft: identifier(&c.id) + visioncraft__plan___tQualityPlan->>visioncraft: require(_, #quot;invalid or d…)? + visioncraft__plan___tQualityPlan->>visioncraft: require(_, #quot;aggregate de…)? + visioncraft__plan___tQualityPlan->>visioncraft: require(_, #quot;aggregate de…)? + visioncraft__plan___tQualityPlan->>visioncraft: require(_, #quot;check scope …)? + loop for p in &c.scope + visioncraft__plan___tQualityPlan->>visioncraft: require(_, #quot;scope must u…)? + end + alt Evaluator::ExitCode { success_codes } + visioncraft__plan___tQualityPlan->>visioncraft: require(_, #quot;success_code…)? + else Evaluator::Reported { adapter } + visioncraft__plan___tQualityPlan->>visioncraft: identifier(adapter) + visioncraft__plan___tQualityPlan->>visioncraft: require(identifier(), #quot;reported eva…)? + end + end + loop for e in &self.expectations + visioncraft__plan___tQualityPlan->>visioncraft: identifier(&e.id) + visioncraft__plan___tQualityPlan->>visioncraft: require(_, #quot;invalid or d…)? + visioncraft__plan___tQualityPlan->>visioncraft: nonempty(&e.claim) + visioncraft__plan___tQualityPlan->>visioncraft: require(nonempty(), #quot;expectation …)? + visioncraft__plan___tQualityPlan->>visioncraft: require(_, #quot;expectation …)? + visioncraft__plan___tQualityPlan->>visioncraft: require(_, #quot;regression-c…)? + opt let Some(s) = &e.stabilizer + visioncraft__plan___tQualityPlan->>visioncraft: nonempty(&s.test_id) + visioncraft__plan___tQualityPlan->>visioncraft: require(_, #quot;invalid stab…)? + end + opt let Some(c) = &e.positive_control + visioncraft__plan___tQualityPlan->>visioncraft: require(_, #quot;positive con…)? + end + opt e.category != EvidenceCategory::Executable + visioncraft__plan___tQualityPlan->>visioncraft: require(is_some_and(), #quot;partial/manu…)? + end + end +``` diff --git a/docs/diagrams/generated/src/process.rs.md b/docs/diagrams/generated/src/process.rs.md new file mode 100644 index 0000000..ba628ce --- /dev/null +++ b/docs/diagrams/generated/src/process.rs.md @@ -0,0 +1,87 @@ +--- +sealmap: 2 +source: src/process.rs +module: "sym:cargo visioncraft . process/" +language: rust +source_hash: blake3:b24b8fb96eba5f197c4a00e8da464df9d6d53b98c4db058f9b684e8da1c64e3c +lines: 425 +fragments: 2 +--- +# `sym:cargo visioncraft . process/` · src/process.rs +> Bounded local command execution. + +## structure +```mermaid +classDiagram + direction LR + class visioncraft__process___tCapturedRun["CapturedRun"] { + <> + +termination: Termination + +exit_code: Option#lt;i32#gt; + +signal: Option#lt;i32#gt; + +started_at_ms: u64 + +finished_at_ms: u64 + +elapsed_ms: u64 + +stdout: PathBuf + +stderr: PathBuf + +error: Option#lt;String#gt; + } + class visioncraft__process___tTermination["Termination"] { + <> + Completed + Unavailable + FailedToStart + TimedOut + Interrupted + CaptureFailed + } + class visioncraft__process["visioncraft::process"] { + <> + +private_directory(path: &Path) io::Result#lt;#40;#41;#gt; + +private_file(path: &Path) io::Result#lt;File#gt; + +run_command(invocation: &Invocation, root: &Path, output: &Path, cancelled: &AtomicBool, inherit_stdin: bool,) io::Result#lt;CapturedRun#gt; + ~run_command_with_env(crate) io::Re… + } + class visioncraft__plan___tInvocation["Invocation"] { + <> + } + visioncraft__process ..> visioncraft__plan___tInvocation + visioncraft__process ..> visioncraft__process___tCapturedRun + visioncraft__process___tCapturedRun *-- visioncraft__process___tTermination : termination +``` + +## `sym:cargo visioncraft . process/run_command_with_env().` +`pub(crate) fn run_command_with_env(invocation: &Invocation, root: &Path, output: &Path, cancelled: &AtomicBool, inherit_stdin: bool, overrides: &std::collections::BTreeMap,) -> io::Re…` · L225-L425 +```mermaid +sequenceDiagram + participant visioncraft__process as process mod + participant visioncraft__plan___tInvocation as Invocation + participant _nix as nix ext + visioncraft__process->>visioncraft__plan___tInvocation: validate() + visioncraft__process->>visioncraft__process: unix_now() + visioncraft__process->>visioncraft__process: private_file(&stdout_path)? + visioncraft__process->>visioncraft__process: private_file(&stderr_path)? + opt cancelled.load(Ordering::SeqCst) + Note over visioncraft__process: return Ok(result) + end + opt invocation.timeout_ms == 0 || invocation.max_output_… + Note over visioncraft__process: return Err(io::Error::new(io::ErrorKind::InvalidInput, … + end + opt Err(err) + visioncraft__process->>visioncraft__process: unix_now() + Note over visioncraft__process: return Ok(result) + end + visioncraft__process->>visioncraft__process: capture(expect(), stdout_file, clone(), clone(), clone(… + visioncraft__process->>visioncraft__process: capture(expect(), stderr_file, total, clone(), clone(),… + opt result.termination == Termination::Completed + opt via is_ok_and + visioncraft__process->>_nix: Pid::from_raw(p) + visioncraft__process->>_nix: signal::killpg(from_raw(), None) + end + end + opt result.termination != Termination::Completed + visioncraft__process->>visioncraft__process: signal_group(pid, SIGINT) + visioncraft__process->>visioncraft__process: signal_group(pid, SIGKILL) + end + visioncraft__process->>visioncraft__process: unix_now() +``` From 2c5a625ce245be2a5ec2f0b30633d708b50afb9e Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 3 Nov 2026 11:38:25 +0000 Subject: [PATCH 13/16] Close independent review findings and make evidence freshness explicit --- .github/workflows/ci.yml | 9 +- .gitignore | 1 + Cargo.toml | 2 +- README.md | 25 ++- docs/REVIEW-2026-11-03.md | 28 ++++ docs/UPSTREAM-DEEPSEC.md | 15 ++ src/cli.rs | 71 +++++---- src/deepsec.rs | 66 +++++++- src/deepsec_evidence.rs | 8 +- src/evaluate.rs | 23 ++- src/git_metadata.rs | 30 ++++ src/lib.rs | 3 + src/main.rs | 3 +- src/process.rs | 324 ++++++++++++++++++++++++++++++++++++-- tests/deepsec.rs | 42 +++++ tests/native_cli.rs | 152 ++++++++++++++++++ tests/process.rs | 83 ++++++++++ 17 files changed, 813 insertions(+), 72 deletions(-) create mode 100644 docs/REVIEW-2026-11-03.md create mode 100644 src/git_metadata.rs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5d764e1..b4862cc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -25,6 +25,13 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 - - uses: dtolnay/rust-toolchain@cfcaf53ba4c621917ec7f78a66bff7a8848ddad4 # 1.85.0 + - uses: dtolnay/rust-toolchain@360a4e93673de6630fac2478bc9e35244b01a759 # 1.88.0 - run: cargo check --locked --all-targets - run: cargo check --locked --no-default-features + diagrams: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 + - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable + - run: cargo install sealmap --version '=0.4.0' --locked + - run: sealmap generate . --name visioncraft --public-only --min-calls 4 --no-model --out docs/diagrams/generated --check diff --git a/.gitignore b/.gitignore index 1358b31..f6e0442 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ /.visioncraft/ /.deepsec-gate/ /.task-evidence/ +/.claude-flow/ diff --git a/Cargo.toml b/Cargo.toml index 42294c7..45ecbb9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -2,7 +2,7 @@ name = "visioncraft" version = "0.1.0" edition = "2024" -rust-version = "1.85" +rust-version = "1.88" description = "Explicit quality plans, bounded execution receipts and deterministic evidence gates" license = "MIT OR Apache-2.0" repository = "https://github.com/DreamLab-AI/visioncraft" diff --git a/README.md b/README.md index 4920b41..be7a925 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ It is not proof of correctness, security, complete test coverage or deployment. ## Install -Rust 1.85 or later is required. The process CLI currently supports Unix. +Rust 1.88 or later is required. The process CLI currently supports Unix. ```sh cargo install visioncraft --locked --version 0.1.0 @@ -78,6 +78,24 @@ receipt cannot satisfy the new input. Create a new plan and fresh run directory after intentionally changing a check's scope or configuration. Existing output paths are refused to avoid overwriting evidence. +Repository and configuration labels are caller declarations. Without +`--current-subject`, evaluation reports their freshness as +`plan-declared-unverified`; the CLI observes the selected source snapshot, but +does not discover repository identity or configuration from the environment. +To attest current labels, supply a current `Subject` JSON record: + +```sh +visioncraft evaluate quality.json --receipts evidence-1 \ + --current-subject current-subject.json --json +``` + +The CLI checks that record's source fields against disk and treats its +repository/configuration fields as `caller-attested`. Different labels make the +old evidence stale; matching labels remain attestations. A configuration digest +in a label is not automatically verified against a file. Include the actual +configuration artifact in `--input` to check its bytes; changed selected +configuration invalidates the evidence even if the label stays unchanged. + For a real project, include relevant source, lockfiles and configuration in `--input`; pass required environment **names** with repeated `--env` options. Only named environment variables are inherited. Set useful `--timeout-ms` and @@ -213,10 +231,15 @@ process groups support cancellation and deadlines, but a deliberately escaping process or a blocked kernel filesystem call needs host-level containment. Private capture directories protect ordinary local handling, not a hostile concurrent filesystem. Keep source-bearing evidence out of public commits. +Linux can recognise exited zombie group members through an unrestricted `/proc` +view; hidden, unreadable or uncertain state remains non-passing. Other Unix +platforms conservatively reject any surviving group, including zombies. Run `cargo test`, `cargo clippy --all-targets -- -D warnings`, `cargo fmt --check` and `RUSTDOCFLAGS='-D warnings' cargo doc --no-deps`. The [implementation contract](docs/EXPECTATIONS.md) records acceptance boundaries. +The [release review](docs/REVIEW-2026-11-03.md) records reproduced counterexamples +and their dispositions. [Zeroshot lessons](docs/ZEROSHOT-LESSONS.md) document source-grounded design patterns adopted without importing another execution engine. Structural skill checks and forward evaluations are reported separately from diff --git a/docs/REVIEW-2026-11-03.md b/docs/REVIEW-2026-11-03.md new file mode 100644 index 0000000..f56d485 --- /dev/null +++ b/docs/REVIEW-2026-11-03.md @@ -0,0 +1,28 @@ +# Release review and counterexamples — 3 November 2026 + +A separate Claude Sonnet 5.5 investigation through Deepsec 2.3.10 reviewed ten +selected production files at `6f233886824ef3896cbd8c18fd35fc3b9fbc2bb6`, retaining +source hashes, model records, captures and findings. It found six issues. The +original gate receipt is `ERROR`, because the process runner reported lingering +descendants; that receipt has not been relabelled as a pass. Raw evidence remains +in the host's `visioncraft-20261103/adversarial/attempt-1` evidence archive. + +| Finding | Disposition and control | +| --- | --- | +| Credential variable and provider URL are selected by policy | Trusted caller boundary, documented in the upstream guide. Policy must not come from an untrusted repository. An environment-name prefix would not establish recipient authority. | +| Git metadata honours repository filesystem-monitor configuration | Reproduced by a hook creating an unexpected file. Both CLI paths now share restricted metadata arguments/environment; the same control passes without executing the hook. | +| Nested review checkpoint paths can redirect writes | Reproduced with symlinks at data, nested file and ignore paths. Bounded recursive inspection rejects links and special files before invoking the external tool; the ignore file is replaced privately. | +| Repository/configuration labels appear automatically freshness-checked | The CLI now distinguishes observed source bytes from opaque caller declarations. Explicit current-subject labels feed the core comparison; changed configuration bytes must be selected inputs for automatic verification. | +| Invalid Unicode argument panics on the parser error path | Reproduced as exit 101. The error path now inspects OS strings; malformed arguments retain the documented exit codes. | +| A zombie process group member causes a false capture failure | Reproduced separately from the live-descendant control. Linux checks distinguish proven exited group members from live or unknown state; other Unix platforms remain conservative. | + +The first Agentbox review also identified private JSON-write and placeholder +expansion defects. Their reproductions, repairs and trust-boundary disposition +belong to the consuming repository's `docs/developer/visioncraft-host-review.md`. +The host's review reported partial scope and remains non-passing; findings are +still useful hypotheses and do not imply complete review coverage. + +The first fresh CI run separately caught a rustdoc link and a Rust 1.85 claim +that a transitive dependency could not satisfy. The link was corrected and the +declared minimum raised to Rust 1.88, with an explicit CI job. Test success and +review completion remain separate release evidence. diff --git a/docs/UPSTREAM-DEEPSEC.md b/docs/UPSTREAM-DEEPSEC.md index c50fe29..7907d14 100644 --- a/docs/UPSTREAM-DEEPSEC.md +++ b/docs/UPSTREAM-DEEPSEC.md @@ -96,6 +96,21 @@ release, change default models, initialise accounts or start paid reviews. ## Host responsibilities +The invoking user and host-projected policy are trusted configuration. Treat +`--policy-json`, executable lookup through `PATH`, credential environment names +and provider URLs with the same authority as starting the reviewer directly. +Never derive them from an untrusted repository's contents. HTTP remains available +for explicitly configured local providers; the host owns transport and endpoint +approval. A name prefix would not establish that trust or authorise a recipient. + +Metadata probes share the native CLI's restricted Git environment and disable +repository filesystem-monitor hooks. Review checkpoints reject symlinks, hard +links and special files throughout the bounded state tree before invoking +Deepsec, and rewrite their ignore file privately. Existing ordinary checkpoint +records are not proof of a fresh review: current run identity and exact source +hashes remain required. These checks do not isolate concurrent writers with the +same Unix identity or the reviewer's own tools. + VisionCraft never implicitly installs Deepsec, runs `init` or login, changes global defaults, or chooses a new credential provider. It does not create a sandbox: the invoked reviewer and its children have the authority granted by diff --git a/src/cli.rs b/src/cli.rs index 0f658e9..d80ef2d 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -3,6 +3,11 @@ //! Evaluation only reads source and evidence plus fixed Git metadata commands. //! Commands in imported receipts are never replayed. All source coverage and test //! observations remain unknown unless supplied by an actual observer/adapter. +//! Repository and configuration labels are caller declarations, never inferred +//! identities or independently verified configuration digests. Their freshness +//! is unverified without `--current-subject`; that option attests current labels +//! while the CLI independently checks its selected source snapshot. Include +//! actual configuration artifacts in the selected inputs to verify their bytes. use std::collections::BTreeSet; use std::fs::{self, File}; @@ -96,9 +101,10 @@ struct InitOptions { id: String, #[arg(long, default_value = "check")] check: String, + /// Caller-declared component label; defaults to the root directory name. #[arg(long)] repository: Option, - /// Features, target and fixture relevant to this check. + /// Caller-declared features/target/fixture label, not an observed digest. #[arg(long)] configuration: String, #[arg(long, default_value = ".")] @@ -144,7 +150,8 @@ struct EvaluateOptions { /// relative to this file's parent, which must be a private evidence root. #[arg(long)] context: Option, - /// Optional current-subject JSON, verified against the actual selected files. + /// Attest current repository/configuration labels in Subject JSON; source + /// fields are checked against disk. Labels/digests are not auto-discovered. #[arg(long)] current_subject: Option, /// Inject evaluation time in Unix milliseconds; defaults to the current clock. @@ -349,18 +356,8 @@ fn git(root: &Path, args: &[&str], cancelled: &AtomicBool) -> Result = [ - "--no-pager", - "--literal-pathspecs", - "-c", - "core.fsmonitor=false", - "-c", - "core.untrackedCache=false", - "-C", - ] - .into_iter() - .map(str::to_owned) - .collect(); + let mut argv = crate::git_metadata::prefix(); + argv.push("-C".into()); argv.push( root.to_str() .ok_or_else(|| { @@ -372,17 +369,7 @@ fn git(root: &Path, args: &[&str], cancelled: &AtomicBool) -> Result = [ - ("GIT_OPTIONAL_LOCKS", "0"), - ("GIT_NO_LAZY_FETCH", "1"), - ("GIT_NO_REPLACE_OBJECTS", "1"), - ("GIT_TERMINAL_PROMPT", "0"), - ("GIT_CONFIG_NOSYSTEM", "1"), - ("GIT_CONFIG_GLOBAL", "/dev/null"), - ] - .into_iter() - .map(|(name, value)| (name.into(), value.into())) - .collect(); + let fixed = crate::git_metadata::fixed_environment(); let mut env = vec!["PATH".into()]; env.extend(fixed.keys().cloned()); let invocation = Invocation { @@ -689,10 +676,10 @@ fn evidence_parent(root: &Path, path: &str) -> Result { return Err(error(2, "artifact output path is not confined")); } let path = root.join(path); - if let Some(parent) = path.parent() { - if !parent.exists() { - process::private_directory(parent).map_err(io_error)?; - } + if let Some(parent) = path.parent() + && !parent.exists() + { + process::private_directory(parent).map_err(io_error)?; } output_path(&path) } @@ -986,9 +973,7 @@ fn evaluate_options(options: EvaluateOptions, cancelled: &AtomicBool) -> Result< let (_, bytes) = read_explicit(path, MAX_JSON)?; let supplied: Subject = crate::from_json(&bytes).map_err(invalid)?; supplied.validate().map_err(invalid)?; - if supplied.repository != current.repository - || supplied.configuration != current.configuration - || supplied.revision != current.revision + if supplied.revision != current.revision || supplied.inputs != current.inputs || supplied.dirty != current.dirty { @@ -997,6 +982,11 @@ fn evaluate_options(options: EvaluateOptions, cancelled: &AtomicBool) -> Result< "supplied current subject contradicts the observed source snapshot", )); } + // These opaque labels come from the current caller, not from Git or a + // copy of the reviewed plan. The core can now detect attested drift; + // matching labels remain attestations rather than independent proof. + current.repository = supplied.repository; + current.configuration = supplied.configuration; } let mut verified = VerifiedArtifacts::default(); let mut receipts = Vec::new(); @@ -1051,8 +1041,20 @@ fn evaluate_options(options: EvaluateOptions, cancelled: &AtomicBool) -> Result< .map_err(invalid)?; } let report = crate::evaluate(&plan, &receipts, &context); + let label_basis = if options.current_subject.is_some() { + "caller-attested" + } else { + "plan-declared-unverified" + }; if options.json { - print_json(&report)?; + let mut output = serde_json::to_value(&report).map_err(invalid)?; + output["freshness"] = serde_json::json!({ + "source_snapshot": "observed", + "repository": label_basis, + "configuration": label_basis, + "configuration_artifacts": "selected-inputs-only" + }); + print_json(&output)?; } else { println!( "{:?}: {}/{} required checks passed; {} expectation(s)", @@ -1061,6 +1063,9 @@ fn evaluate_options(options: EvaluateOptions, cancelled: &AtomicBool) -> Result< report.required_checks, report.expectations.len() ); + println!( + "Repository/configuration freshness: {label_basis}; labels and digests are not independently verified (select configuration artifacts as inputs)." + ); for check in &report.checks { println!( "{}: {:?} — {}", diff --git a/src/deepsec.rs b/src/deepsec.rs index e561eea..861b2b1 100644 --- a/src/deepsec.rs +++ b/src/deepsec.rs @@ -1,10 +1,10 @@ //! Executed Deepsec 2.3.10 gates with explicit policy and retained error states. //! //! This adapter knows no Agentbox manifest, memory service or network address. -//! Hosts project their policy into [`DeepsecPolicy`]. Credentials remain named +//! Hosts project their policy into [`crate::deepsec::DeepsecPolicy`]. Credentials remain named //! environment variables and are passed only to the model-processing child. -use crate::process::{Termination, private_directory, private_file, run_command}; +use crate::process::{Termination, private_directory, private_file, run_command_with_env}; use crate::{Invocation, from_json, sha256}; use clap::{ArgGroup, Args}; use serde::{Deserialize, Serialize}; @@ -498,11 +498,22 @@ impl Attempt<'_> { let directory = self.report.join(format!("{:02}-{stage}", self.sequence)); self.sequence += 1; private_directory(&directory).map_err(io_error)?; + let (args, env, fixed) = if program == "git" { + let mut hardened = crate::git_metadata::prefix(); + hardened.extend(args); + ( + hardened, + vec!["PATH".into()], + crate::git_metadata::fixed_environment(), + ) + } else { + (args, environment(self.policy, model), BTreeMap::new()) + }; let invocation = Invocation { program: program.into(), args, cwd: ".".into(), - env: environment(self.policy, model), + env, timeout_ms: remaining.as_millis().max(1).try_into().unwrap_or(u64::MAX), max_output_bytes: self.policy.max_output_bytes, }; @@ -511,8 +522,8 @@ impl Attempt<'_> { &serde_json::to_vec_pretty(&invocation) .map_err(|_| error(70, "invocation serialisation failed"))?, )?; - let run = - run_command(&invocation, cwd, &directory, self.cancelled, stdin).map_err(io_error)?; + let run = run_command_with_env(&invocation, cwd, &directory, self.cancelled, stdin, &fixed) + .map_err(io_error)?; let stdout = read_bounded(&run.stdout, self.policy.max_output_bytes)?; let stderr = read_bounded(&run.stderr, self.policy.max_output_bytes)?; let mut log = OpenOptions::new() @@ -568,6 +579,42 @@ fn workspace_lock(workspace: &Path) -> Result, GateError .map_err(|_| error(78, "another review owns this workspace")) } +#[cfg(unix)] +fn validate_workspace_tree(workspace: &Path) -> Result<(), GateError> { + use std::os::unix::fs::MetadataExt; + // Deepsec owns durable checkpoint state here. Reject redirected/special + // entries before passing that tree to an external tool with credentials. + // This does not isolate concurrent writers running as the same Unix user. + let mut pending = vec![(workspace.to_owned(), 0_usize)]; + let mut count = 0_usize; + while let Some((directory, depth)) = pending.pop() { + if depth > 64 { + return Err(error(78, "review workspace exceeds traversal bounds")); + } + for entry in fs::read_dir(directory).map_err(io_error)? { + count += 1; + if count > 100_000 { + return Err(error(78, "review workspace exceeds traversal bounds")); + } + let entry = entry.map_err(io_error)?; + let meta = fs::symlink_metadata(entry.path()).map_err(io_error)?; + if meta.file_type().is_symlink() + || !(meta.is_dir() || meta.is_file()) + || (meta.is_file() && meta.nlink() != 1) + { + return Err(error( + 78, + "review workspace contains redirected or special entries", + )); + } + if meta.is_dir() { + pending.push((entry.path(), depth + 1)); + } + } + } + Ok(()) +} + /// Execute an explicitly requested security gate, returning its legacy exit code. /// /// Dry-run prints only the resolved plan. Completed, failed and interrupted @@ -717,6 +764,7 @@ pub fn execute(options: &DeepsecOptions, cancelled: &AtomicBool) -> Result Result Result, GateError> { if set.len() >= 100_000 { return Err(error(70, "review history exceeds limit")); } - if let Some(name) = item.file_name().to_str() { - if name.ends_with(".json") { - set.insert(name.to_owned()); - } + if let Some(name) = item.file_name().to_str() + && name.ends_with(".json") + { + set.insert(name.to_owned()); } } Ok(set) diff --git a/src/evaluate.rs b/src/evaluate.rs index 0501c85..536c3d3 100644 --- a/src/evaluate.rs +++ b/src/evaluate.rs @@ -220,10 +220,10 @@ fn check_receipt( if output_bytes > check.invocation.max_output_bytes { return error("verified raw output exceeds configured capture limit"); } - if let Some(snapshot) = &receipt.subject.working_tree { - if !context.verified.contains(snapshot) { - return error("dirty working-tree snapshot has not been byte-verified"); - } + if let Some(snapshot) = &receipt.subject.working_tree + && !context.verified.contains(snapshot) + { + return error("dirty working-tree snapshot has not been byte-verified"); } match &receipt.observed_scope { Some(paths) if !check.scope.iter().all(|p| paths.contains(p)) => { @@ -560,15 +560,14 @@ pub fn evaluate( if let Err(error) = receipt.validate() { report.errors.push(error.to_string()); } - if let Some(check) = plan.checks.iter().find(|c| c.id == receipt.check_id) { - if receipt.plan_sha256 != digest + if let Some(check) = plan.checks.iter().find(|c| c.id == receipt.check_id) + && (receipt.plan_sha256 != digest || receipt.subject != plan.subject - || receipt.invocation != check.invocation - { - report - .errors - .push("receipt does not bind to its declared plan/subject/invocation".into()); - } + || receipt.invocation != check.invocation) + { + report + .errors + .push("receipt does not bind to its declared plan/subject/invocation".into()); } if !ids.contains(receipt.check_id.as_str()) { report diff --git a/src/git_metadata.rs b/src/git_metadata.rs new file mode 100644 index 0000000..b201f65 --- /dev/null +++ b/src/git_metadata.rs @@ -0,0 +1,30 @@ +//! Shared policy for read-only Git metadata inspection, not user build commands. +use std::collections::BTreeMap; + +pub(crate) fn prefix() -> Vec { + [ + "--no-pager", + "--literal-pathspecs", + "-c", + "core.fsmonitor=false", + "-c", + "core.untrackedCache=false", + ] + .into_iter() + .map(str::to_owned) + .collect() +} + +pub(crate) fn fixed_environment() -> BTreeMap { + [ + ("GIT_OPTIONAL_LOCKS", "0"), + ("GIT_NO_LAZY_FETCH", "1"), + ("GIT_NO_REPLACE_OBJECTS", "1"), + ("GIT_TERMINAL_PROMPT", "0"), + ("GIT_CONFIG_NOSYSTEM", "1"), + ("GIT_CONFIG_GLOBAL", "/dev/null"), + ] + .into_iter() + .map(|(name, value)| (name.into(), value.into())) + .collect() +} diff --git a/src/lib.rs b/src/lib.rs index 1d94a81..a74c076 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -127,3 +127,6 @@ pub mod deepsec; /// Explicit command-line and filesystem adapter for the quality core. #[cfg(feature = "cli")] pub mod cli; + +#[cfg(feature = "cli")] +mod git_metadata; diff --git a/src/main.rs b/src/main.rs index 5ebd2cc..29c24cd 100644 --- a/src/main.rs +++ b/src/main.rs @@ -10,7 +10,8 @@ fn main() -> ExitCode { Err(error) => { let failed = error.use_stderr(); let _ = error.print(); - let legacy = std::env::args().nth(1).as_deref() == Some("deepsec"); + let legacy = + std::env::args_os().nth(1).as_deref() == Some(std::ffi::OsStr::new("deepsec")); return ExitCode::from(if !failed { 0 } else if legacy { diff --git a/src/process.rs b/src/process.rs index 2139bc7..62e8766 100644 --- a/src/process.rs +++ b/src/process.rs @@ -186,9 +186,298 @@ fn capture( #[cfg(unix)] fn signal_group(pid: u32, signal: nix::sys::signal::Signal) { - if let Ok(pid) = i32::try_from(pid) { - if pid > 1 { - let _ = nix::sys::signal::killpg(nix::unistd::Pid::from_raw(pid), signal); + if let Ok(pid) = i32::try_from(pid) + && pid > 1 + { + let _ = nix::sys::signal::killpg(nix::unistd::Pid::from_raw(pid), signal); + } +} + +#[cfg(unix)] +fn group_probe(result: Result<(), nix::errno::Errno>) -> io::Result { + match result { + Ok(()) => Ok(true), + Err(nix::errno::Errno::ESRCH) => Ok(false), + Err(error) => Err(io::Error::from(error)), + } +} + +#[cfg(unix)] +fn group_running(pid: u32, deadline: Instant) -> io::Result { + use nix::sys::signal::killpg; + use nix::unistd::Pid; + let group = i32::try_from(pid) + .ok() + .filter(|pid| *pid > 1) + .ok_or_else(|| io::Error::other("invalid process group"))?; + if !group_probe(killpg(Pid::from_raw(group), None))? { + return Ok(false); + } + #[cfg(target_os = "linux")] + { + // Signal 0 proves existence, not execution: zombies still occupy groups. + linux_proc::group_running(group, deadline) + } + #[cfg(not(target_os = "linux"))] + { + let _ = deadline; + // Without a supported state observer, an existing group remains unsafe. + Ok(true) + } +} + +#[cfg(target_os = "linux")] +mod linux_proc { + use super::*; + use nix::unistd::{Pid, getpgid}; + use std::collections::BTreeSet; + + fn unknown() -> io::Error { + io::Error::other("process group state could not be established") + } + + fn bounded_read(path: &Path, limit: u64) -> io::Result> { + let mut bytes = Vec::new(); + File::open(path)?.take(limit + 1).read_to_end(&mut bytes)?; + if bytes.len() as u64 > limit { + return Err(unknown()); + } + Ok(bytes) + } + + // comm may contain spaces, parentheses, newlines or non-UTF-8 bytes. Only + // parse the numeric prefix and fields after the final closing parenthesis. + fn state(bytes: &[u8], expected_pid: u32, expected_group: Option) -> io::Result { + let space = bytes.iter().position(|c| *c == b' ').ok_or_else(unknown)?; + let close = bytes + .windows(2) + .rposition(|s| s == b") ") + .ok_or_else(unknown)?; + let pid = std::str::from_utf8(&bytes[..space]) + .ok() + .and_then(|s| s.parse::().ok()); + if pid != Some(expected_pid) || bytes.get(space + 1) != Some(&b'(') || close <= space + 1 { + return Err(unknown()); + } + let text = std::str::from_utf8(&bytes[close + 2..]).map_err(|_| unknown())?; + let mut fields = text.split_ascii_whitespace(); + let status = fields + .next() + .filter(|s| s.len() == 1) + .ok_or_else(unknown)? + .as_bytes()[0]; + fields + .next() + .and_then(|s| s.parse::().ok()) + .ok_or_else(unknown)?; + let group = fields + .next() + .and_then(|s| s.parse::().ok()) + .ok_or_else(unknown)?; + if expected_group.is_some_and(|expected| group != expected) { + return Err(unknown()); + } + Ok(status) + } + + fn unrestricted(mounts: &str) -> bool { + let mut found = false; + for line in mounts.lines() { + let fields: Vec<_> = line.split_ascii_whitespace().collect(); + if fields.get(1) == Some(&"/proc") { + if fields.get(2) != Some(&"proc") { + return false; + } + let Some(options) = fields.get(3) else { + return false; + }; + if options + .split(',') + .any(|o| o.starts_with("hidepid=") && o != "hidepid=0" && o != "hidepid=off") + { + return false; + } + found = true; + } + } + found + } + + fn ids(path: &Path, deadline: Instant) -> io::Result> { + let mut ids = Vec::new(); + for entry in fs::read_dir(path)? { + if Instant::now() >= deadline { + return Err(io::Error::new( + io::ErrorKind::TimedOut, + "process observation deadline", + )); + } + let name = entry?.file_name(); + if let Some(id) = name.to_str().and_then(|s| s.parse::().ok()) { + ids.push(id); + if ids.len() > 65_536 { + return Err(unknown()); + } + } + } + Ok(ids) + } + + fn dead(state: u8) -> bool { + matches!(state, b'Z' | b'X' | b'x') + } + + fn no_longer_member(pid: u32, group: i32) -> io::Result { + match getpgid(Some(Pid::from_raw( + i32::try_from(pid).map_err(|_| unknown())?, + ))) { + Ok(actual) => Ok(actual.as_raw() != group), + Err(nix::errno::Errno::ESRCH) => Ok(true), + Err(error) => Err(io::Error::from(error)), + } + } + + fn tasks_dead(process: &Path, group: i32, deadline: Instant) -> io::Result { + let tasks = ids(&process.join("task"), deadline)?; + if tasks.is_empty() { + return Err(unknown()); + } + for tid in tasks { + let record = match bounded_read(&process.join(format!("task/{tid}/stat")), 8192) { + Ok(record) => record, + Err(error) + if error.kind() == io::ErrorKind::NotFound && no_longer_member(tid, group)? => + { + continue; + } + Err(error) => return Err(error), + }; + if !dead(state(&record, tid, Some(group))?) { + return Ok(false); + } + } + Ok(true) + } + + fn dead_members(group: i32, deadline: Instant) -> io::Result>> { + let mut members = BTreeSet::new(); + for pid in ids(Path::new("/proc"), deadline)? { + if no_longer_member(pid, group)? { + continue; + } + let process = PathBuf::from(format!("/proc/{pid}")); + let record = match bounded_read(&process.join("stat"), 8192) { + Ok(record) => record, + Err(error) + if error.kind() == io::ErrorKind::NotFound && no_longer_member(pid, group)? => + { + continue; + } + Err(error) => return Err(error), + }; + if !dead(state(&record, pid, Some(group))?) { + return Ok(None); + } + // A zombie thread-group leader can still have executing threads. + // Missing/unreadable task information cannot prove they have exited. + match tasks_dead(&process, group, deadline) { + Ok(true) => (), + Ok(false) => return Ok(None), + Err(error) + if error.kind() == io::ErrorKind::NotFound && no_longer_member(pid, group)? => + { + continue; + } + Err(error) => return Err(error), + } + members.insert(pid); + } + Ok(Some(members)) + } + + pub(super) fn group_running(group: i32, deadline: Instant) -> io::Result { + let mounts = bounded_read(Path::new("/proc/mounts"), 1_048_576)?; + if !unrestricted(std::str::from_utf8(&mounts).map_err(|_| unknown())?) { + return Err(unknown()); + } + // A proc mount for another PID namespace cannot establish membership. + state( + &bounded_read(Path::new("/proc/self/stat"), 8192)?, + std::process::id(), + None, + )?; + let mut previous = None; + for _ in 0..3 { + let Some(members) = dead_members(group, deadline)? else { + return Ok(true); + }; + if members.is_empty() { + return if super::group_probe(nix::sys::signal::killpg(Pid::from_raw(group), None))? + { + Err(unknown()) + } else { + Ok(false) + }; + } + // Retry only changes to this group. Unrelated process churn must not + // make a completed command fail on a busy host. + if previous.as_ref() == Some(&members) { + return Ok(false); + } + previous = Some(members); + } + Err(unknown()) + } + + #[cfg(test)] + mod tests { + use super::*; + + #[test] + fn stat_handles_unusual_names_and_never_calls_live_states_dead() { + for status in b"RS DTtWKPIZXx".iter().filter(|c| **c != b' ') { + let mut record = b"123 (odd ) \xff name) ".to_vec(); + record.push(*status); + record.extend_from_slice(b" 1 456 0 0"); + let observed = state(&record, 123, Some(456)).unwrap(); + assert_eq!(dead(observed), matches!(status, b'Z' | b'X' | b'x')); + } + assert!(state(b"123 (test) Z 1 456", 124, Some(456)).is_err()); + assert!(state(b"123 (test) Z 1 456", 123, Some(457)).is_err()); + assert!(state(b"123 (test) Z", 123, None).is_err()); + } + + #[test] + fn hidden_or_missing_proc_views_are_not_complete_observations() { + assert!(unrestricted("proc /proc proc rw,hidepid=0 0 0\n")); + assert!(unrestricted("proc /proc proc rw,hidepid=off 0 0\n")); + assert!(!unrestricted("proc /proc proc rw,hidepid=2 0 0\n")); + assert!(!unrestricted("proc /proc proc rw,hidepid=ptraceable 0 0\n")); + assert!(!unrestricted("tmpfs /proc tmpfs rw 0 0\n")); + assert!(!unrestricted("")); + } + + #[test] + fn zombie_leader_does_not_hide_a_live_thread_or_unreadable_state() { + let root = tempfile::tempdir().unwrap(); + for (tid, status) in [(123, "Z"), (124, "S")] { + let path = root.path().join(format!("task/{tid}")); + fs::create_dir_all(&path).unwrap(); + fs::write(path.join("stat"), format!("{tid} (fixture) {status} 1 456")).unwrap(); + } + let deadline = Instant::now() + Duration::from_secs(1); + assert!(!tasks_dead(root.path(), 456, deadline).unwrap()); + fs::write(root.path().join("task/124/stat"), "124 (fixture) Z 1 456").unwrap(); + assert!(tasks_dead(root.path(), 456, deadline).unwrap()); + fs::write(root.path().join("task/124/stat"), "unreadable record").unwrap(); + assert!(tasks_dead(root.path(), 456, deadline).is_err()); + } + + #[test] + fn permission_and_other_probe_errors_do_not_mean_absent() { + assert!(!super::super::group_probe(Err(nix::errno::Errno::ESRCH)).unwrap()); + assert!(super::super::group_probe(Err(nix::errno::Errno::EPERM)).is_err()); + assert!(super::super::group_probe(Err(nix::errno::Errno::EINVAL)).is_err()); } } } @@ -203,6 +492,10 @@ fn signal_group(pid: u32, signal: nix::sys::signal::Signal) { /// Unix execution uses a new process group and stops that group on interruption, /// deadline, capture failure or lingering descendants. Non-Unix execution is /// explicitly unsupported rather than claiming unimplemented child cleanup. +/// Linux excludes zombie/dead group members only after bounded, unrestricted +/// proc observations, including their threads. Unknown or unreadable membership +/// remains a failure. Other Unix systems conservatively reject any surviving +/// process group, including unreaped zombies. No subreaper state is changed. pub fn run_command( invocation: &Invocation, root: &Path, @@ -247,8 +540,7 @@ pub(crate) fn run_command_with_env( } #[cfg(unix)] { - use nix::sys::signal::{Signal, killpg}; - use nix::unistd::Pid; + use nix::sys::signal::Signal; use std::os::unix::process::{CommandExt, ExitStatusExt}; invocation.validate().map_err(|_| { io::Error::new(io::ErrorKind::InvalidInput, "invalid invocation contract") @@ -360,12 +652,22 @@ pub(crate) fn run_command_with_env( }; if result.termination == Termination::Completed { // A completed parent must not strand background writers or spenders. - let group_alive = - i32::try_from(pid).is_ok_and(|p| p > 1 && killpg(Pid::from_raw(p), None).is_ok()); - if group_alive { - result.termination = Termination::CaptureFailed; - result.error = Some("process left unfinished descendants".into()); - } else { + match group_running(pid, start + Duration::from_millis(invocation.timeout_ms)) { + Ok(true) => { + result.termination = Termination::CaptureFailed; + result.error = Some("process left unfinished descendants".into()); + } + Err(error) => { + result.termination = if error.kind() == io::ErrorKind::TimedOut { + Termination::TimedOut + } else { + Termination::CaptureFailed + }; + result.error = Some("could not establish process group completion".into()); + } + Ok(false) => (), + } + if result.termination == Termination::Completed { // A slow filesystem flush is not evidence of a live descendant. while !stdout.is_finished() || !stderr.is_finished() { if cancelled.load(Ordering::SeqCst) { diff --git a/tests/deepsec.rs b/tests/deepsec.rs index ffce1ba..286cd5d 100644 --- a/tests/deepsec.rs +++ b/tests/deepsec.rs @@ -110,6 +110,48 @@ fn actual_review_and_threshold_have_positive_controls() { ); } } + +#[test] +fn metadata_does_not_execute_repository_fsmonitor() { + let f = Fixture::new("pass"); + let marker = f.root.join("unexpected-hook"); + assert!( + Command::new("git") + .args(["config", "core.fsmonitor", "touch unexpected-hook"]) + .current_dir(&f.root) + .status() + .unwrap() + .success() + ); + let output = f.gate(); + assert_eq!(output.status.code(), Some(0)); + assert!( + !marker.exists(), + "metadata inspection executed repository config" + ); +} + +#[test] +fn review_state_refuses_nested_symlinks_before_external_tools() { + use std::os::unix::fs::symlink; + for nested in ["data", "data/repo/files", ".gitignore"] { + let f = Fixture::new("pass"); + let state = f.root.join(".deepsec-gate"); + let path = state.join(nested); + fs::create_dir_all(path.parent().unwrap()).unwrap(); + let outside = f._temp.path().join("outside"); + fs::create_dir(&outside).unwrap(); + symlink(&outside, path).unwrap(); + let output = f.gate(); + assert_eq!( + output.status.code(), + Some(78), + "{nested}: {}", + String::from_utf8_lossy(&output.stderr) + ); + assert_eq!(fs::read_dir(outside).unwrap().count(), 0); + } +} #[test] fn no_empty_partial_or_ambiguous_review_can_pass() { for case in [ diff --git a/tests/native_cli.rs b/tests/native_cli.rs index 5a0f7a3..f408033 100644 --- a/tests/native_cli.rs +++ b/tests/native_cli.rs @@ -89,6 +89,158 @@ fn evaluate(root: &Path) -> Output { ) } +#[test] +fn invalid_non_unicode_argv_uses_usage_exit_codes_without_panicking() { + use std::ffi::OsString; + use std::os::unix::ffi::OsStringExt; + let malformed = OsString::from_vec(vec![0xff]); + for legacy in [false, true] { + let mut command = Command::new(env!("CARGO_BIN_EXE_visioncraft")); + if legacy { + command.arg("deepsec"); + } + let output = command.arg(&malformed).output().unwrap(); + assert_eq!( + output.status.code(), + Some(if legacy { 78 } else { 2 }), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + assert!(!String::from_utf8_lossy(&output.stderr).contains("panicked")); + } +} + +#[test] +fn current_labels_are_explicit_attestations_and_can_make_receipts_stale() { + let root = fixture(); + init(root.path(), "printf ok"); + success(&run(root.path())); + let plan = QualityPlan::parse(&fs::read(root.path().join("plan.json")).unwrap()).unwrap(); + let report: serde_json::Value = serde_json::from_slice(&evaluate(root.path()).stdout).unwrap(); + assert_eq!( + report["freshness"]["configuration"], + "plan-declared-unverified" + ); + assert_eq!( + report["freshness"]["repository"], + "plan-declared-unverified" + ); + let args = [ + "evaluate", + "plan.json", + "--receipts", + "evidence", + "--current-subject", + "current.json", + "--json", + ]; + for field in ["configuration", "repository"] { + let mut supplied = serde_json::to_value(&plan.subject).unwrap(); + supplied[field] = serde_json::json!("a different caller-attested context"); + fs::write( + root.path().join("current.json"), + serde_json::to_vec(&supplied).unwrap(), + ) + .unwrap(); + let output = cli(root.path(), &args); + assert_eq!( + output.status.code(), + Some(1), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + let report: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap(); + assert_eq!(report["outcome"], "incomplete"); + assert_eq!(report["freshness"][field], "caller-attested"); + assert!( + report + .to_string() + .contains("current repository/configuration differs") + ); + } + fs::write( + root.path().join("current.json"), + serde_json::to_vec(&plan.subject).unwrap(), + ) + .unwrap(); + let same = cli(root.path(), &args); + success(&same); + let report: serde_json::Value = serde_json::from_slice(&same.stdout).unwrap(); + assert_eq!(report["freshness"]["source_snapshot"], "observed"); + assert_eq!(report["freshness"]["configuration"], "caller-attested"); + let mut forged = plan.subject; + forged.inputs[0].sha256 = "0".repeat(64); + fs::write( + root.path().join("current.json"), + serde_json::to_vec(&forged).unwrap(), + ) + .unwrap(); + assert_eq!(cli(root.path(), &args).status.code(), Some(2)); +} + +#[test] +fn configuration_artifact_bytes_are_checked_only_when_selected_as_inputs() { + let root = fixture(); + fs::write( + root.path().join("configuration.json"), + "{\"enabled\":true}\n", + ) + .unwrap(); + git(root.path(), &["add", "configuration.json"]); + git( + root.path(), + &[ + "-c", + "user.name=Fixture", + "-c", + "user.email=fixture@example.invalid", + "commit", + "-qm", + "configuration", + ], + ); + let digest = visioncraft::sha256(&fs::read(root.path().join("configuration.json")).unwrap()); + success(&cli( + root.path(), + &[ + "plan", + "init", + "--out", + "plan.json", + "--input", + "source.txt", + "--input", + "configuration.json", + "--configuration", + &digest, + "--", + "/bin/sh", + "-c", + "exit 0", + ], + )); + success(&run(root.path())); + success(&evaluate(root.path())); + fs::write( + root.path().join("configuration.json"), + "{\"enabled\":false}\n", + ) + .unwrap(); + let changed = evaluate(root.path()); + assert_eq!(changed.status.code(), Some(1)); + let report: serde_json::Value = serde_json::from_slice(&changed.stdout).unwrap(); + assert_eq!(report["outcome"], "incomplete"); + assert_eq!( + report["freshness"]["configuration"], + "plan-declared-unverified" + ); + assert!( + report + .to_string() + .contains("selected source inputs changed") + ); +} + #[test] fn plan_run_and_evaluate_use_real_output_but_do_not_invent_scope_or_tests() { use std::os::unix::fs::PermissionsExt; diff --git a/tests/process.rs b/tests/process.rs index ea3897f..ae14161 100644 --- a/tests/process.rs +++ b/tests/process.rs @@ -110,6 +110,89 @@ fn output_limit_and_lingering_background_processes_cannot_pass() { assert_eq!(result.termination, Termination::CaptureFailed); } +#[cfg(target_os = "linux")] +fn completed_leader_with_group_member(exited: bool) -> visioncraft::process::CapturedRun { + use std::os::unix::process::CommandExt; + use std::process::{Child, Command, Stdio}; + + struct Reap(Child); + impl Drop for Reap { + fn drop(&mut self) { + let _ = self.0.kill(); + let _ = self.0.wait(); + } + } + + let root = tempfile::tempdir().unwrap(); + let out = root.path().join("attempt"); + private_directory(&out).unwrap(); + std::thread::scope(|scope| { + let worker = scope.spawn(|| { + run_command( + &invocation( + "printf '%s' \"$$\" > group; while [ ! -e release ]; do sleep 0.01; done", + ), + root.path(), + &out, + &AtomicBool::new(false), + false, + ) + .unwrap() + }); + let deadline = Instant::now() + Duration::from_secs(1); + let group = loop { + if let Ok(raw) = fs::read_to_string(root.path().join("group")) + && let Ok(pid) = raw.parse::() + { + break pid; + } + assert!(Instant::now() < deadline, "fixture leader did not start"); + std::thread::sleep(Duration::from_millis(5)); + }; + // The test owns this member, so its zombie is reproducible even with a + // reaping init, and cleanup can wait it without changing subreaper state. + let member = Reap( + Command::new("sh") + .args(["-c", if exited { "exit 0" } else { "exec sleep 30" }]) + .process_group(group) + .stdin(Stdio::null()) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .spawn() + .unwrap(), + ); + if exited { + loop { + let stat = fs::read_to_string(format!("/proc/{}/stat", member.0.id())).unwrap(); + if stat.rsplit_once(") ").unwrap().1.starts_with("Z ") { + break; + } + assert!(Instant::now() < deadline, "fixture member did not exit"); + std::thread::sleep(Duration::from_millis(5)); + } + } + fs::write(root.path().join("release"), "ready").unwrap(); + let result = worker.join().unwrap(); + drop(member); + result + }) +} + +#[cfg(target_os = "linux")] +#[test] +fn exited_unreaped_group_member_does_not_fail_completed_capture() { + let result = completed_leader_with_group_member(true); + assert_eq!(result.termination, Termination::Completed, "{result:?}"); + assert_eq!(result.exit_code, Some(0)); +} + +#[cfg(target_os = "linux")] +#[test] +fn live_group_member_with_closed_streams_cannot_pass() { + let result = completed_leader_with_group_member(false); + assert_eq!(result.termination, Termination::CaptureFailed, "{result:?}"); +} + #[test] fn cancellation_and_missing_program_are_explicit() { let root = tempfile::tempdir().unwrap(); From b4ed6419abe9671b27a393fc2d7da8e040f0d309 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 3 Nov 2026 11:39:00 +0000 Subject: [PATCH 14/16] Refresh verified ADRs and source-derived diagrams after review repairs --- docs/adr/0001-portable-quality-contract.md | 8 +- .../0002-specialist-upstream-boundaries.md | 3 +- docs/diagrams/README.md | 9 +- docs/diagrams/generated/_index.json | 2 +- docs/diagrams/generated/_overview.md | 17 ++- docs/diagrams/generated/src/cli.rs.md | 51 ++++--- docs/diagrams/generated/src/deepsec.rs.md | 24 ++- .../generated/src/deepsec_evidence.rs.md | 2 +- docs/diagrams/generated/src/evaluate.rs.md | 10 +- .../diagrams/generated/src/git_metadata.rs.md | 22 +++ docs/diagrams/generated/src/lib.rs.md | 5 +- docs/diagrams/generated/src/main.rs.md | 4 +- docs/diagrams/generated/src/process.rs.md | 141 ++++++++++++++++-- 13 files changed, 236 insertions(+), 62 deletions(-) create mode 100644 docs/diagrams/generated/src/git_metadata.rs.md diff --git a/docs/adr/0001-portable-quality-contract.md b/docs/adr/0001-portable-quality-contract.md index 2a31a84..546bc10 100644 --- a/docs/adr/0001-portable-quality-contract.md +++ b/docs/adr/0001-portable-quality-contract.md @@ -3,13 +3,14 @@ id: ADR-0001 title: Portable quality contracts with explicit execution adapters status: accepted date: 2026-11-03 -verified_commit: 6f233886824ef3896cbd8c18fd35fc3b9fbc2bb6 +verified_commit: 2c5a625ce245be2a5ec2f0b30633d708b50afb9e verified_paths: - src/plan.rs - src/evidence.rs - src/evaluate.rs - src/cli.rs - src/process.rs + - src/git_metadata.rs - Cargo.toml --- @@ -30,6 +31,11 @@ Plans bind code/configuration and literal invocations; aggregate admission bound are checked before execution. Required missing, incomplete or contradicted evidence cannot become a pass by omission. Observed coverage is distinct from intended scope. +The native CLI observes source snapshots directly. Repository and configuration +identifiers are caller declarations, explicitly labelled as unverified when no +current-subject attestation is supplied. Include configuration files in the +selected inputs when their exact bytes must be checked automatically. + Optional Unix process/CLI adapters execute explicit commands with private captures, deadlines and process-group cancellation. Read-only evaluation never executes an imported receipt's command. Fixed Git metadata probes use the same bounded runner, diff --git a/docs/adr/0002-specialist-upstream-boundaries.md b/docs/adr/0002-specialist-upstream-boundaries.md index da1feb4..c8ce276 100644 --- a/docs/adr/0002-specialist-upstream-boundaries.md +++ b/docs/adr/0002-specialist-upstream-boundaries.md @@ -4,10 +4,11 @@ title: Consume specialist reviewers through versioned upstream contracts status: accepted date: 2026-11-03 depends_on: [ADR-0001] -verified_commit: 6f233886824ef3896cbd8c18fd35fc3b9fbc2bb6 +verified_commit: 2c5a625ce245be2a5ec2f0b30633d708b50afb9e verified_paths: - src/deepsec.rs - src/deepsec_evidence.rs + - src/git_metadata.rs - contracts/deepsec.json - contracts/agentic-qe.json - skills/visioncraft/references/agentic-qe.md diff --git a/docs/diagrams/README.md b/docs/diagrams/README.md index e6b2bab..0355979 100644 --- a/docs/diagrams/README.md +++ b/docs/diagrams/README.md @@ -4,7 +4,8 @@ The [generated overview](generated/_overview.md) and [per-source index](generated/_index.json) are extracted by Sealmap 0.4.0. Each source document has source hashes, symbol identities, spans and call confidence. Generated views are read-only; edit code and regenerate rather than hand-editing -the output. +the output. CI installs the pinned Sealmap 0.4.0 release and checks this corpus +against the candidate source. ```sh sealmap generate . --name visioncraft --public-only --min-calls 4 --no-model \ @@ -19,9 +20,9 @@ consumption. Source extraction, Mermaid rendering and runtime verification are separate observations. The following authored view is verified against source at -`6f233886824ef3896cbd8c18fd35fc3b9fbc2bb6`: `src/cli.rs:1096`, -`src/plan.rs:295`, `src/evaluate.rs:532`, `src/process.rs:206`, -`src/deepsec.rs:576` and `src/deepsec_evidence.rs:220`. +`2c5a625ce245be2a5ec2f0b30633d708b50afb9e`: `src/cli.rs:1101`, +`src/plan.rs:295`, `src/evaluate.rs:532`, `src/process.rs:499`, +`src/deepsec.rs:623` and `src/deepsec_evidence.rs:220`. ```mermaid flowchart TD diff --git a/docs/diagrams/generated/_index.json b/docs/diagrams/generated/_index.json index e533d08..fa0efed 100644 --- a/docs/diagrams/generated/_index.json +++ b/docs/diagrams/generated/_index.json @@ -1 +1 @@ -{"schema_version":2,"generator":"sealmap-corpus 0.4.0","codebase":"visioncraft","stats":{"files":9,"symbols":151,"relations":572,"flows":69,"calls":492},"documents":[{"source":"src/cli.rs","document":"src/cli.rs.md","module":"sym:cargo visioncraft . cli/","source_hash":"blake3:e883c6b79fba490bdf06476058ca4078ae6ce7a147e4308b65afd6c1326bdb7d","document_hash":"blake3:2220d5663cc889f21a54f8c8a819780e390a596c34834a2d205ba1879dacf41d","fragments":[{"id":"structure:src/cli.rs","kind":"structure","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/","span":{"start_line":1,"start_col":1,"end_line":1130,"end_col":1},"sig_hash":"blake3-16:a91e60562b65dab9be5fcfdd480a0025","body_hash":"blake3-16:40b5981fc262f7a390bc06718d7992c7","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft . cli/Cli#","sym:cargo visioncraft . cli/CliError#","sym:cargo visioncraft . cli/ContextFile#","sym:cargo visioncraft . cli/EvaluateOptions#","sym:cargo visioncraft . cli/ExpectationCommand#","sym:cargo visioncraft . cli/FamilyDeclaration#","sym:cargo visioncraft . cli/GateCommand#","sym:cargo visioncraft . cli/GitOutput#","sym:cargo visioncraft . cli/InitOptions#","sym:cargo visioncraft . cli/Operation#","sym:cargo visioncraft . cli/PlanCommand#","sym:cargo visioncraft . cli/RunOptions#","sym:cargo visioncraft . cli/SnapshotInput#"],"hash":"blake3:cc028d12f950c3ae1e85c12d11800b79b52157876e4bc9dd1614e6a982724168"},{"id":"sym:cargo visioncraft . cli/confined().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/confined().","span":{"start_line":218,"start_col":1,"end_line":244,"end_col":2},"sig_hash":"blake3-16:0f062b609af0623484ee4a8f3ce0791c","body_hash":"blake3-16:4d6d3d8c0f03abdfbfa2e19fad43f067","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":222},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":223},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":228},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":233},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":241}],"hash":"blake3:10134bbd7624f9bdd4c0c962084ddf99406fd07aaff1c112d8e6fde98e6256d2"},{"id":"sym:cargo visioncraft . cli/read_explicit().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/read_explicit().","span":{"start_line":266,"start_col":1,"end_line":278,"end_col":2},"sig_hash":"blake3-16:0135480ca8cad65a15367671ed65406d","body_hash":"blake3-16:2795f0c0dbe9df2e76d5b564e531760e","participants":["sym:cargo visioncraft . cli/"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":267},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":275},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":276,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":277}],"hash":"blake3:ea44521ca2c9580a30bcd4324260bf263e6d214f80c0579223fe16ef7cab9f86"},{"id":"sym:cargo visioncraft . cli/output_path().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/output_path().","span":{"start_line":280,"start_col":1,"end_line":305,"end_col":2},"sig_hash":"blake3-16:dbdb74d9394b0d29e9e3e8e51c008181","body_hash":"blake3-16:ca6d64c44631f2c0ee6c2ac804186a41","participants":["sym:cargo visioncraft . cli/"],"calls":[{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":289},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":295},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":297},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":299},{"target":"sym:cargo visioncraft . cli/io_error().","confidence":"exact","line":301}],"hash":"blake3:16ae04e0f4143479ef97deccd15f1e0d6c9c12d1f16c3de82ed63430b15466ec"},{"id":"sym:cargo visioncraft . cli/write_new().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/write_new().","span":{"start_line":307,"start_col":1,"end_line":319,"end_col":2},"sig_hash":"blake3-16:2d4d3f36490d72b3f6dc2d027eca4f3e","body_hash":"blake3-16:697a3ac4de3c725a30cfdc25488b8f86","participants":["sym:cargo visioncraft . cli/","sym:extern tempfile"],"calls":[{"target":"sym:cargo visioncraft . cli/output_path().","confidence":"exact","line":308,"expands":"sym:cargo visioncraft . cli/output_path()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":311},{"target":"sym:extern tempfile::NamedTempFile::new_in","confidence":"external","line":312},{"target":"sym:cargo visioncraft . cli/io_error().","confidence":"exact","line":317}],"hash":"blake3:457d2ebe0c5c2371326d12fd034f42e6ec1b554309aa824f919c052357d114df"},{"id":"sym:cargo visioncraft . cli/git().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/git().","span":{"start_line":338,"start_col":1,"end_line":418,"end_col":2},"sig_hash":"blake3-16:4841aa17643eae3fb5fe09d3badd3661","body_hash":"blake3-16:8785ef8586f97909ef447f795faf923b","participants":["sym:cargo visioncraft . cli/","sym:extern tempfile","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:extern tempfile::Builder::new","confidence":"external","line":339},{"target":"sym:extern tempfile::Builder::prefix","confidence":"external","line":340},{"target":"sym:extern tempfile::Builder::permissions","confidence":"external","line":344},{"target":"sym:extern tempfile::Builder::tempdir","confidence":"external","line":346},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":367},{"target":"sym:cargo visioncraft . process/run_command_with_env().","confidence":"exact","line":396,"expands":"sym:cargo visioncraft . process/run_command_with_env()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":408},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":410},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":411},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":412},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":413}],"hash":"blake3:430d4a769fcdfe36e5428007d37c2d7f77410f3778f3213d86dd937208bcfb58"},{"id":"sym:cargo visioncraft . cli/revision().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/revision().","span":{"start_line":420,"start_col":1,"end_line":430,"end_col":2},"sig_hash":"blake3-16:0b6fb7f218212ea850ac236d821d8a54","body_hash":"blake3-16:57f70fb943003d553d789a8ac8afdf57","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":421,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":423},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":426},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":427}],"hash":"blake3:6a47990d6e52a53cd8a184d578ac35266d83543a99f35ac8eb40a6ae358444e3"},{"id":"sym:cargo visioncraft . cli/selected_dirty().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/selected_dirty().","span":{"start_line":432,"start_col":1,"end_line":497,"end_col":2},"sig_hash":"blake3-16:466ae4a23ec9651aa81d4bed047fce21","body_hash":"blake3-16:60c71d02d369ba96d0e8ac250beb706a","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":437,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":439},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":450},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":452},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":458},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":465},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":466},{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":468,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":470},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":473},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":477},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":479},{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":481,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":483},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":485},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":487,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":488},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":492}],"hash":"blake3:453ed573926bd3366697d5f770d078d6675b2d10fc95e5d42b91b2998b8b86df"},{"id":"sym:cargo visioncraft . cli/inputs().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/inputs().","span":{"start_line":506,"start_col":1,"end_line":534,"end_col":2},"sig_hash":"blake3-16:ed0d5f7af2c90806f98bbe55046295b0","body_hash":"blake3-16:a4fe913978641a3fc470a6673895dbdd","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":509,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":512},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":512},{"target":"sym:cargo visioncraft . cli/io_error().","confidence":"exact","line":522},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":524}],"hash":"blake3:3f2dccdf84b13932d2d5f50d867c14fdcb3bccb66ede478c1abcba1fd56cc8a7"},{"id":"sym:cargo visioncraft . cli/source_snapshot().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/source_snapshot().","span":{"start_line":536,"start_col":1,"end_line":570,"end_col":2},"sig_hash":"blake3-16:99ceb13e4265b3151783ffc6a3e45c52","body_hash":"blake3-16:cbf9aee3425988e9536de14608e8da81","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:extern sealmap_corpus"],"calls":[{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":545,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":545},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":548},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":553},{"target":"sym:extern sealmap_corpus::review::Artifact::iter","confidence":"external","line":555},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":558},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":569}],"hash":"blake3:f3d87fe2bf48f895fb27ad21313f2b1c7930ba3db6156c76295df6bb381ab3a4"},{"id":"sym:cargo visioncraft . cli/init().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/init().","span":{"start_line":577,"start_col":1,"end_line":665,"end_col":2},"sig_hash":"blake3-16:b4e883cfce087fb3dfc81327eb4ad912","body_hash":"blake3-16:b5e11d29744c7e97abe293abd262f6ed","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":578},{"target":"sym:cargo visioncraft . cli/output_path().","confidence":"exact","line":579,"expands":"sym:cargo visioncraft . cli/output_path()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":583},{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":586},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":587},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":590,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":591,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/selected_dirty().","confidence":"exact","line":592,"expands":"sym:cargo visioncraft . cli/selected_dirty()."},{"target":"sym:cargo visioncraft . cli/source_snapshot().","confidence":"exact","line":594,"expands":"sym:cargo visioncraft . cli/source_snapshot()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":602},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":607},{"target":"sym:cargo visioncraft . plan/QualityPlan#validate().","confidence":"exact","line":647,"expands":"sym:cargo visioncraft . plan/QualityPlan#validate()."},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":648,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":649,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":650},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":653},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":655},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":656,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":658,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":660},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":660,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":661}],"hash":"blake3:2bd9ae15fbaff3cd2eec8f3f3539d22c3dd9870def20c2e0f278d9303ee76f01"},{"id":"sym:cargo visioncraft . cli/add_artifact().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/add_artifact().","span":{"start_line":667,"start_col":1,"end_line":675,"end_col":2},"sig_hash":"blake3-16:f0e71327596608de7e6b1f6a54853e2d","body_hash":"blake3-16:9b18aea04b32a8ac770134c2c7b25309","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . evidence/VerifiedArtifacts#"],"calls":[{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":672},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":673,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":673},{"target":"sym:cargo visioncraft . evidence/VerifiedArtifacts#insert().","confidence":"exact","line":674}],"hash":"blake3:9ab7e24505a5f71cd2e61508e0fabb0e233106589d756559b7851f0b72d83d88"},{"id":"sym:cargo visioncraft . cli/evidence_parent().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/evidence_parent().","span":{"start_line":687,"start_col":1,"end_line":698,"end_col":2},"sig_hash":"blake3-16:db2e97ad57784510b3ed00e2d46b651b","body_hash":"blake3-16:fb22ab4b05dcead0e83f694da33d202f","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":688},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":689},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":694},{"target":"sym:cargo visioncraft . cli/output_path().","confidence":"exact","line":697,"expands":"sym:cargo visioncraft . cli/output_path()."}],"hash":"blake3:937c15cb58ce91ca5a1f5e89aa9fcb15fec58a6dc29926f3858b097b62d99e3c"},{"id":"sym:cargo visioncraft . cli/run().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/run().","span":{"start_line":772,"start_col":1,"end_line":928,"end_col":2},"sig_hash":"blake3-16:ba17c27738cfde5ad2571ad58ca94d50","body_hash":"blake3-16:08da835ef954e7dd9cc676a5efc8ef47","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . process/","sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft . evidence/ExecutionReceipt#"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":773},{"target":"sym:cargo visioncraft . cli/read_plan().","confidence":"exact","line":774},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":781},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":785},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":790,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":793,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":794,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":796},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":803,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":803},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":804},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":805},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":809},{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":810},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":811,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":812},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":812,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/evidence_parent().","confidence":"exact","line":814,"expands":"sym:cargo visioncraft . cli/evidence_parent()."},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":814,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":819,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":820,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":822},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":827,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":830},{"target":"sym:cargo visioncraft . cli/executable().","confidence":"exact","line":831},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":836},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":843},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":844},{"target":"sym:cargo visioncraft . process/run_command().","confidence":"exact","line":850},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":854},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":854},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":858},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":858},{"target":"sym:cargo visioncraft . cli/process_status().","confidence":"exact","line":860},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":866,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . plan/QualityPlan#digest().","confidence":"inferred","line":885},{"target":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","confidence":"exact","line":909,"expands":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":911},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":911,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/execution_exit().","confidence":"exact","line":912},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":924}],"hash":"blake3:f85f4c799e989e52e1d019de0ab972275cb43e5195f141cb2ea2d324af9bb903"},{"id":"sym:cargo visioncraft . cli/load_receipts().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/load_receipts().","span":{"start_line":930,"start_col":1,"end_line":960,"end_col":2},"sig_hash":"blake3-16:c5944f1ef230b917228e3114fc3f9133","body_hash":"blake3-16:8e82d035d63b0fd789327e31b5b9794c","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft . evidence/ExecutionReceipt#"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":934},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":941},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":946,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":953},{"target":"sym:cargo visioncraft . evidence/ExecutionReceipt#parse().","confidence":"exact","line":953},{"target":"sym:cargo visioncraft . cli/receipt_artifacts().","confidence":"exact","line":954},{"target":"sym:cargo visioncraft . cli/add_artifact().","confidence":"exact","line":955,"expands":"sym:cargo visioncraft . cli/add_artifact()."}],"hash":"blake3:cc786ac0e563e162c5bd861f9c216fe9ef10f557e6eeb37a0b004e691b4aa023"},{"id":"sym:cargo visioncraft . cli/evaluate_options().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/evaluate_options().","span":{"start_line":962,"start_col":1,"end_line":1089,"end_col":2},"sig_hash":"blake3-16:e24a4e8e44d00858f88e500a666ef939","body_hash":"blake3-16:858b9ee3ab3c6ae5aa824a3fc4a3361c","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . plan/Subject#","sym:cargo visioncraft . evidence/VerifiedArtifacts#","sym:cargo visioncraft . cli/ContextFile#","sym:cargo visioncraft . evaluate/EvaluationContext#","sym:extern sealmap_corpus","sym:cargo visioncraft . evaluate/"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":963},{"target":"sym:cargo visioncraft . cli/read_plan().","confidence":"exact","line":964},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":967,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":968,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":971},{"target":"sym:cargo visioncraft . cli/selected_dirty().","confidence":"exact","line":976,"expands":"sym:cargo visioncraft . cli/selected_dirty()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":980},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":980},{"target":"sym:cargo visioncraft . cli/read_explicit().","confidence":"exact","line":986,"expands":"sym:cargo visioncraft . cli/read_explicit()."},{"target":"sym:cargo visioncraft . from_json().","confidence":"exact","line":987},{"target":"sym:cargo visioncraft . plan/Subject#validate().","confidence":"exact","line":988,"expands":"sym:cargo visioncraft . plan/Subject#validate()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":995},{"target":"sym:cargo visioncraft . evidence/VerifiedArtifacts#default().","confidence":"inferred","line":1001},{"target":"sym:cargo visioncraft . cli/load_receipts().","confidence":"exact","line":1004,"expands":"sym:cargo visioncraft . cli/load_receipts()."},{"target":"sym:cargo visioncraft . cli/ContextFile#default().","confidence":"inferred","line":1006},{"target":"sym:cargo visioncraft . cli/read_explicit().","confidence":"exact","line":1008,"expands":"sym:cargo visioncraft . cli/read_explicit()."},{"target":"sym:cargo visioncraft . from_json().","confidence":"exact","line":1009},{"target":"sym:cargo visioncraft . cli/add_artifact().","confidence":"exact","line":1016,"expands":"sym:cargo visioncraft . cli/add_artifact()."},{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":1021,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . evaluate/EvaluationContext#new().","confidence":"exact","line":1036},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":1043},{"target":"sym:extern sealmap_corpus::route::Family::named","confidence":"external","line":1049},{"target":"sym:cargo visioncraft . evaluate/","confidence":"exact","line":1053},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":1055}],"hash":"blake3:7124460731cfad155822a2220dc78fdfd21fd8ce1785f8349845d2bf7272b849"},{"id":"sym:cargo visioncraft . cli/execute().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/execute().","span":{"start_line":1091,"start_col":1,"end_line":1130,"end_col":2},"sig_hash":"blake3-16:46912e87ff2e1ea76267f5fc634b601d","body_hash":"blake3-16:38f8733b2f66f86957663943eeb3898d","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft . deepsec/"],"calls":[{"target":"sym:cargo visioncraft . cli/init().","confidence":"exact","line":1100,"expands":"sym:cargo visioncraft . cli/init()."},{"target":"sym:cargo visioncraft . cli/read_plan().","confidence":"exact","line":1104},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":1106},{"target":"sym:cargo visioncraft . cli/run().","confidence":"exact","line":1118,"expands":"sym:cargo visioncraft . cli/run()."},{"target":"sym:cargo visioncraft . cli/evaluate_options().","confidence":"exact","line":1125,"expands":"sym:cargo visioncraft . cli/evaluate_options()."},{"target":"sym:cargo visioncraft . deepsec/execute().","confidence":"exact","line":1127,"expands":"sym:cargo visioncraft . deepsec/execute()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":1127}],"hash":"blake3:b33cd48ba99d0f8f35cf65973f7f754430fcf32c4df4237059c40674dbd2c4ce"}]},{"source":"src/deepsec.rs","document":"src/deepsec.rs.md","module":"sym:cargo visioncraft . deepsec/","source_hash":"blake3:fe5f7e3e8985a7eeb253589267c66d64771af816b56d031e6022a81c9b5649ae","document_hash":"blake3:a7bd7e112ce044a49036d54efa5933063519d48a052877314b60cbe9957d3078","fragments":[{"id":"structure:src/deepsec.rs","kind":"structure","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/","span":{"start_line":1,"start_col":1,"end_line":1013,"end_col":1},"sig_hash":"blake3-16:dfca6b22e7a0f75576ee19430ce800ad","body_hash":"blake3-16:1aca4af380a6989c4105fd15f821635e","participants":["sym:cargo visioncraft . deepsec/","sym:cargo visioncraft . deepsec/Attempt#","sym:cargo visioncraft . deepsec/DeepsecOptions#","sym:cargo visioncraft . deepsec/DeepsecPolicy#","sym:cargo visioncraft . deepsec/GateError#","sym:cargo visioncraft . deepsec/StrictJson#"],"hash":"blake3:6eecc34c285fec9c493ea0145ea40bfa7badb172c994b1257ff76b6d5cbb9329"},{"id":"sym:cargo visioncraft . deepsec/DeepsecPolicy#validate().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/DeepsecPolicy#validate().","span":{"start_line":142,"start_col":5,"end_line":229,"end_col":6},"sig_hash":"blake3-16:8e9590b4e5ea930dbb967d625e57fb57","body_hash":"blake3-16:0aaf1b920c2175079b0541e62429279d","participants":["sym:cargo visioncraft . deepsec/DeepsecPolicy#","sym:cargo visioncraft . deepsec/","sym:extern url"],"calls":[{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":146},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":149},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":152},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":155},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":161},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":167},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":180},{"target":"sym:extern url::Url::parse","confidence":"external","line":183},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":184},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":192},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":200},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":206},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":216},{"target":"sym:cargo visioncraft . deepsec/duration_ms().","confidence":"exact","line":223},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":224}],"hash":"blake3:abe7fa45bd5abad24561011927a3cf90fe983f66bed974955fbc0f150c2a401a"},{"id":"sym:cargo visioncraft . deepsec/findings().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/findings().","span":{"start_line":371,"start_col":1,"end_line":410,"end_col":2},"sig_hash":"blake3-16:d958a149d303f700360dacf89d848981","body_hash":"blake3-16:d23d0fceb0331f95373edce172a94932","participants":["sym:cargo visioncraft . deepsec/","sym:extern serde_json"],"calls":[{"target":"sym:extern serde_json::from_slice","confidence":"external","line":372},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":373},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":378},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":388},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":395},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":402},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":405}],"hash":"blake3:730cdc58cc3f43348c0dce498d29c1d82277e0e08fec90504dd8015cc12953c5"},{"id":"sym:cargo visioncraft . deepsec/Attempt#command().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/Attempt#command().","span":{"start_line":484,"start_col":5,"end_line":548,"end_col":6},"sig_hash":"blake3-16:e8c318eaf968b6ab917a2c6d444e8f2e","body_hash":"blake3-16:ef8d2a7f7c72094b0cb60dabb4f9b121","participants":["sym:cargo visioncraft . deepsec/Attempt#","sym:cargo visioncraft . deepsec/","sym:cargo visioncraft . process/","sym:extern serde_json"],"calls":[{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":497},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":500},{"target":"sym:cargo visioncraft . deepsec/environment().","confidence":"exact","line":505},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":511},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":512},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":509},{"target":"sym:cargo visioncraft . process/run_command().","confidence":"exact","line":515},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":516},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":517},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":528},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":529},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":526},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":534},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":537},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":538},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":542},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":546}],"hash":"blake3:0e56cbbb57cdab018658379f226bc56185480bd619b7b7f2166c99bcb40c0c55"},{"id":"sym:cargo visioncraft . deepsec/execute().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/execute().","span":{"start_line":571,"start_col":1,"end_line":975,"end_col":2},"sig_hash":"blake3-16:0ba905b365d196f55d4ed680e35ea604","body_hash":"blake3-16:3dc354700b8e8a66aff3d048432af924","participants":["sym:cargo visioncraft . deepsec/","sym:cargo visioncraft .","sym:cargo visioncraft . deepsec/DeepsecPolicy#","sym:extern serde_json","sym:cargo visioncraft . process/","sym:extern tempfile","sym:cargo visioncraft . deepsec/Attempt#","sym:extern recorded"],"calls":[{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":588},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":593},{"target":"sym:cargo visioncraft . from_json().","confidence":"exact","line":598},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":599},{"target":"sym:cargo visioncraft . deepsec/DeepsecPolicy#[Default]default().","confidence":"exact","line":600},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":619},{"target":"sym:cargo visioncraft . deepsec/root_for().","confidence":"exact","line":624},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":632},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":633},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":634},{"target":"sym:extern serde_json::to_string_pretty","confidence":"external","line":695},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":696},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":704},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":711},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":713},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":715},{"target":"sym:cargo visioncraft . deepsec/workspace_lock().","confidence":"exact","line":719},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":721},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":723},{"target":"sym:cargo visioncraft . process/private_file().","confidence":"exact","line":724},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":727},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":728},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":725},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":731},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":735},{"target":"sym:extern serde_json::to_string_pretty","confidence":"external","line":741},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":742},{"target":"sym:extern tempfile::NamedTempFile::new_in","confidence":"external","line":744},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":749},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":762,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/supported_version().","confidence":"exact","line":782},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":783},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":788,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":799,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:extern recorded::select","confidence":"external","line":810},{"target":"sym:extern recorded::snapshot","confidence":"external","line":811},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":814},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":815},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":812},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":818},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":845,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":847},{"target":"sym:extern recorded::pending","confidence":"external","line":856},{"target":"sym:extern recorded::run_files","confidence":"external","line":860},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":877,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":879},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":882},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":885},{"target":"sym:extern recorded::snapshot","confidence":"external","line":890},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":893},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":894},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":891},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":897},{"target":"sym:extern recorded::validate_review","confidence":"external","line":899},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":919,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":921},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":923},{"target":"sym:cargo visioncraft . deepsec/findings().","confidence":"exact","line":924,"expands":"sym:cargo visioncraft . deepsec/findings()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":926},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":965},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":966},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":963},{"target":"sym:extern serde_json::to_string_pretty","confidence":"external","line":970},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":971}],"hash":"blake3:8fd1ce1ed88cc8c90a1a8107ad0c2c15c5f9a973974decf767c1e1bdf4743b4c"}]},{"source":"src/deepsec_evidence.rs","document":"src/deepsec_evidence.rs.md","module":"sym:cargo visioncraft . deepsec_evidence/","source_hash":"blake3:7bdca6b97bbbee14a261123c7f4f1a363cf86abefbaf059141d6e3f8985a36d2","document_hash":"blake3:c32144af4d919d8b30234481ac770eff44d2a1f62ba272789dd3844dd10f0fd2","fragments":[{"id":"structure:src/deepsec_evidence.rs","kind":"structure","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/","span":{"start_line":1,"start_col":1,"end_line":317,"end_col":1},"sig_hash":"blake3-16:d29639f733f43b721a769946fd5c16ea","body_hash":"blake3-16:d66f6f33f98bccb4f22f19fb1b0f7824","participants":["sym:cargo visioncraft . deepsec_evidence/"],"hash":"blake3:2b62a4deed164da5864a4a3b4a5e4bcd5cf0545d80b644f32199c4c096571d9d"},{"id":"sym:cargo visioncraft . deepsec_evidence/confined().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/confined().","span":{"start_line":15,"start_col":1,"end_line":37,"end_col":2},"sig_hash":"blake3-16:339a3f31cc29d571f0d49cac65efa8cf","body_hash":"blake3-16:bfc51a62ae369d14245e4fe1e398ad60","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:cargo visioncraft .","sym:extern visioncraft"],"calls":[{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":16},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":20},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":29},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":33}],"hash":"blake3:b8c9c4216ed7327069ac7d1d1e50af8df2c6387d1660f7931168280d9a740822"},{"id":"sym:cargo visioncraft . deepsec_evidence/snapshot().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/snapshot().","span":{"start_line":38,"start_col":1,"end_line":60,"end_col":2},"sig_hash":"blake3-16:f9fca86ed05e6dea51f36aa77af98298","body_hash":"blake3-16:92e1f22220e61aed17b21bca7709b198","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft","sym:cargo visioncraft ."],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":40},{"target":"sym:cargo visioncraft . deepsec_evidence/confined().","confidence":"exact","line":46,"expands":"sym:cargo visioncraft . deepsec_evidence/confined()."},{"target":"sym:extern visioncraft::read_bounded","confidence":"inferred","line":46},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":49},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":56}],"hash":"blake3:5653bc15ccdd69ddf29a8b3373e42cc5d25cac283259f0cef32cb2a6d5713278"},{"id":"sym:cargo visioncraft . deepsec_evidence/select().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/select().","span":{"start_line":61,"start_col":1,"end_line":169,"end_col":2},"sig_hash":"blake3-16:cc9a89e8f0905b3cb12ddfe8572273b4","body_hash":"blake3-16:a235aab603da0aabd165ee2efd5dc868","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft"],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":71},{"target":"sym:extern visioncraft::read_bounded","confidence":"inferred","line":75},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":103},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":111},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":126},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":132},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":140},{"target":"sym:cargo visioncraft . deepsec_evidence/confined().","confidence":"exact","line":146,"expands":"sym:cargo visioncraft . deepsec_evidence/confined()."},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":160},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":162}],"hash":"blake3:5bb9a75aa00caea45c6e4b56b2814cf5c9c73123ebbc47fc505690ae8c94d101"},{"id":"sym:cargo visioncraft . deepsec_evidence/run_files().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/run_files().","span":{"start_line":170,"start_col":1,"end_line":193,"end_col":2},"sig_hash":"blake3-16:6da82f7f40f25f96425a127fb162af24","body_hash":"blake3-16:f0009e0c5095006ec53f6e0e20d411c1","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft"],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":176},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":178},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":181},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":182},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":184}],"hash":"blake3:1624786ac1edaf9933c59e02458c9e8a45069628a872c991e089a8730adc656e"},{"id":"sym:cargo visioncraft . deepsec_evidence/validate_review().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/validate_review().","span":{"start_line":220,"start_col":1,"end_line":317,"end_col":2},"sig_hash":"blake3-16:48c209a2019e0cdfb19ce0ddd22d8346","body_hash":"blake3-16:bdc3f563f8b939e53ba3780bfde17d48","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern sealmap_corpus","sym:extern serde_json","sym:extern visioncraft","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . deepsec_evidence/run_files().","confidence":"exact","line":229,"expands":"sym:cargo visioncraft . deepsec_evidence/run_files()."},{"target":"sym:cargo visioncraft . deepsec_evidence/object().","confidence":"exact","line":230},{"target":"sym:extern sealmap_corpus::review::Artifact::iter","confidence":"external","line":236},{"target":"sym:cargo visioncraft . deepsec_evidence/file_record().","confidence":"exact","line":240},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":247},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":248},{"target":"sym:extern visioncraft::write_new","confidence":"inferred","line":249},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":251},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":256},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":257},{"target":"sym:extern sealmap_corpus::review::Artifact::len","confidence":"external","line":262},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":264},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":276},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":283},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":286},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":297},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":308}],"hash":"blake3:ae2141692794b47fd4e101b62646dbe9a0868370fb4b96e96f8a8df88584ea13"}]},{"source":"src/evaluate.rs","document":"src/evaluate.rs.md","module":"sym:cargo visioncraft . evaluate/","source_hash":"blake3:e2b3c4721974ba40222309382bfb4dc2a311296e18b7324982cd29215db905a1","document_hash":"blake3:49f9b9ae1dab58503421ea3705215876ab5523eeb615b17bfbd046e1320e83c3","fragments":[{"id":"structure:src/evaluate.rs","kind":"structure","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/","span":{"start_line":1,"start_col":1,"end_line":658,"end_col":1},"sig_hash":"blake3-16:9fe9b147ca2d959744dccbc9bb23ac64","body_hash":"blake3-16:39fb69207c5495b74802e2cffd67c49d","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft . evaluate/CheckOutcome#","sym:cargo visioncraft . evaluate/CheckReport#","sym:cargo visioncraft . evaluate/EvaluationContext#","sym:cargo visioncraft . evaluate/ExpectationReport#","sym:cargo visioncraft . evaluate/GateOutcome#","sym:cargo visioncraft . evaluate/GateReport#"],"hash":"blake3:d5091dfff7bb58c6eb3e49cacb4b5589dcaf0e603efe16f2f4b6f4f74c0df81b"},{"id":"sym:cargo visioncraft . evaluate/check_receipt().","kind":"sequence","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/check_receipt().","span":{"start_line":160,"start_col":1,"end_line":273,"end_col":2},"sig_hash":"blake3-16:ee70d752233f4499288b800fcec0a414","body_hash":"blake3-16:18e0c7a71c752fd52f17a4f9b6b7d029","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft . evidence/ExecutionReceipt#","sym:cargo visioncraft . plan/","sym:cargo visioncraft . evidence/VerifiedArtifacts#"],"calls":[{"target":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","confidence":"exact","line":168,"expands":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate()."},{"target":"sym:cargo visioncraft . plan/same_inputs().","confidence":"exact","line":177},{"target":"sym:cargo visioncraft . evaluate/context_limits().","confidence":"exact","line":183},{"target":"sym:cargo visioncraft . evaluate/age_limit().","confidence":"exact","line":184},{"target":"sym:cargo visioncraft . evidence/VerifiedArtifacts#byte_len().","confidence":"inferred","line":211}],"hash":"blake3:ea42ed5e2650324925cfd3f057ff96494c704a9fb432daa12fdfe317e1020a4c"},{"id":"sym:cargo visioncraft . evaluate/assessment_binding().","kind":"sequence","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/assessment_binding().","span":{"start_line":298,"start_col":1,"end_line":320,"end_col":2},"sig_hash":"blake3-16:e2d6db985ebd381da5d83e24ce107563","body_hash":"blake3-16:7b52282e846da93f2cde20af7045a03b","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":307},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":311},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":312},{"target":"sym:cargo visioncraft . evaluate/age_limit().","confidence":"exact","line":317},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":316}],"hash":"blake3:30162b56ccfa772885e62b9a777b4781fbd01a3957b7eb431ef2feb04c8d50e9"},{"id":"sym:cargo visioncraft . evaluate/expectation_report().","kind":"sequence","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/expectation_report().","span":{"start_line":322,"start_col":1,"end_line":524,"end_col":2},"sig_hash":"blake3-16:60bd522cd3ba06f3d9da1f7b3e90b52b","body_hash":"blake3-16:e4d1797b13f584d6f345f1601b1187e9","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft .","sym:extern sealmap_corpus"],"calls":[{"target":"sym:cargo visioncraft . evaluate/referenced_check().","confidence":"exact","line":333},{"target":"sym:cargo visioncraft . evaluate/referenced_check().","confidence":"exact","line":336},{"target":"sym:cargo visioncraft . evaluate/referenced_check().","confidence":"exact","line":339},{"target":"sym:cargo visioncraft . evaluate/assessment_binding().","confidence":"exact","line":371,"expands":"sym:cargo visioncraft . evaluate/assessment_binding()."},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":381},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":382},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":383},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":380},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":386},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":391},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":400},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":404},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":411},{"target":"sym:extern sealmap_corpus::route::cross_family_with","confidence":"external","line":421},{"target":"sym:cargo visioncraft . evaluate/assessment_binding().","confidence":"exact","line":479,"expands":"sym:cargo visioncraft . evaluate/assessment_binding()."},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":490},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":490},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":489}],"hash":"blake3:621bb154f0bc58def0d9b99839bfb5f7f07500da87de83f718956d20bb7d43f5"}]},{"source":"src/evidence.rs","document":"src/evidence.rs.md","module":"sym:cargo visioncraft . evidence/","source_hash":"blake3:edfe990a885f2bcad685855fe0c87e11878174d676e4414f4f9448e818ca520a","document_hash":"blake3:92db7d2db5b346b252f2fd1d9472793cfc0dda06b4ac5f891e0e98a8629fc804","fragments":[{"id":"structure:src/evidence.rs","kind":"structure","document":"src/evidence.rs.md","symbol":"sym:cargo visioncraft . evidence/","span":{"start_line":1,"start_col":1,"end_line":292,"end_col":1},"sig_hash":"blake3-16:af11808614b221a0d9791b5c9c0aa422","body_hash":"blake3-16:07ca5c0150b9e722b1428c85557ebe66","participants":["sym:cargo visioncraft . evidence/","sym:cargo visioncraft . evidence/Actor#","sym:cargo visioncraft . evidence/AuditReceipt#","sym:cargo visioncraft . evidence/AuditVerdict#","sym:cargo visioncraft . evidence/ExecutionReceipt#","sym:cargo visioncraft . evidence/ManualObservation#","sym:cargo visioncraft . evidence/ProcessStatus#","sym:cargo visioncraft . evidence/ReportedResult#","sym:cargo visioncraft . evidence/VerifiedArtifacts#"],"hash":"blake3:4cac75df033fe3d821a9d0b2c1862cba2880e53086a68efdbae14c83e5830ef8"},{"id":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","kind":"sequence","document":"src/evidence.rs.md","symbol":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","span":{"start_line":107,"start_col":5,"end_line":178,"end_col":6},"sig_hash":"blake3-16:ba67f81a1ab12cfa2f20da686b32f5f9","body_hash":"blake3-16:85e6fc9a46be325577dbc0b80d49e394","participants":["sym:cargo visioncraft . evidence/ExecutionReceipt#","sym:cargo visioncraft .","sym:cargo visioncraft . plan/Subject#","sym:cargo visioncraft . plan/Invocation#","sym:cargo visioncraft . plan/"],"calls":[{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":113},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":115},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":115},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":114},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":118},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":118},{"target":"sym:cargo visioncraft . plan/Subject#validate().","confidence":"exact","line":119,"expands":"sym:cargo visioncraft . plan/Subject#validate()."},{"target":"sym:cargo visioncraft . plan/Invocation#validate().","confidence":"exact","line":120,"expands":"sym:cargo visioncraft . plan/Invocation#validate()."},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":122},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":121},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":126},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":126},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":129},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":129},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":131},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":135},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":140},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":144},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":149},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":155},{"target":"sym:cargo visioncraft . plan/validate_input_paths().","confidence":"exact","line":157},{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":161},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":160},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":167},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":166},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":172},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":172},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":171},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":175}],"hash":"blake3:5d5543a5441c2972246e77d27188c7df4e53e2c8f859470ae0c0453e4c16b416"}]},{"source":"src/lib.rs","document":"src/lib.rs.md","module":"sym:cargo visioncraft .","source_hash":"blake3:337326f4db730b3c5a5b0457e94f425a596bc8dd6d765e3e51bc9d78bc56b9ad","document_hash":"blake3:67ae0071bf62c3820f59479d664ab7c9a51ea020147d508d84659a58c006f878","fragments":[{"id":"structure:src/lib.rs","kind":"structure","document":"src/lib.rs.md","symbol":"sym:cargo visioncraft .","span":{"start_line":1,"start_col":1,"end_line":129,"end_col":1},"sig_hash":"blake3-16:ef5f0989f89148798c9d4374da243656","body_hash":"blake3-16:117cef759286f6dbd432e1a52012ceff","participants":["sym:cargo visioncraft .","sym:cargo visioncraft . ContractError#"],"hash":"blake3:79e67b1adcabdc35ac57b7f5efcfb3e829837c5a64d36093531f2b87d50b14ad"}]},{"source":"src/main.rs","document":"src/main.rs.md","module":"sym:cargo visioncraft_main .","source_hash":"blake3:99d2860c356b50b40860a89032581ec5c2ae5c16e89fca73d9a59be073f78872","document_hash":"blake3:29b1d11fb16398576b5963e7e60910c3a3a592b7f1368c77b460e33966c7659e","fragments":[{"id":"structure:src/main.rs","kind":"structure","document":"src/main.rs.md","symbol":"sym:cargo visioncraft_main .","span":{"start_line":1,"start_col":1,"end_line":38,"end_col":1},"sig_hash":"blake3-16:be7e0aa42067d3874629adeff2b5a523","body_hash":"blake3-16:74e980764c560ee52cd65267ced20ea5","participants":["sym:cargo visioncraft_main ."],"hash":"blake3:6072a92081ad96885a435ab18fa15f7156552c9f5a91ffd3b893d30664f7c127"}]},{"source":"src/plan.rs","document":"src/plan.rs.md","module":"sym:cargo visioncraft . plan/","source_hash":"blake3:a0eaf6b6e34139a3b02ddc3d521d69dc4c064884b96dfe85585b1a1e7da2107d","document_hash":"blake3:52a11da34333ac5b351ee8aecb9f323047782e5c9a5a9c3d35b3707c159fa8f8","fragments":[{"id":"structure:src/plan.rs","kind":"structure","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/","span":{"start_line":1,"start_col":1,"end_line":413,"end_col":1},"sig_hash":"blake3-16:a24f0f42e161b5767c66583d880ff1c1","body_hash":"blake3-16:244666ed06402316b2c9d9f1e3d97726","participants":["sym:cargo visioncraft . plan/","sym:cargo visioncraft . plan/CheckSpec#","sym:cargo visioncraft . plan/Evaluator#","sym:cargo visioncraft . plan/EvidenceCategory#","sym:cargo visioncraft . plan/Expectation#","sym:cargo visioncraft . plan/GatePolicy#","sym:cargo visioncraft . plan/Invocation#","sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft . plan/Stabilizer#","sym:cargo visioncraft . plan/Subject#"],"hash":"blake3:c3b2d48210fcb0809c8dffe5957419f886988159fb60f056c51dd599ada41860"},{"id":"sym:cargo visioncraft . plan/Subject#validate().","kind":"sequence","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/Subject#validate().","span":{"start_line":36,"start_col":5,"end_line":58,"end_col":6},"sig_hash":"blake3-16:cc5a01905f372f11d7204d0e8ae9b415","body_hash":"blake3-16:5c8417ac75b7f4969f36b4094d1bba88","participants":["sym:cargo visioncraft . plan/Subject#","sym:cargo visioncraft .","sym:cargo visioncraft . plan/"],"calls":[{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":41},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":41},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":43},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":42},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":47},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":46},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":50},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":55},{"target":"sym:cargo visioncraft . plan/validate_inputs().","confidence":"exact","line":57}],"hash":"blake3:322d9507a0187eaa308b3d532d47b123850c5a0d98d5ae483d9298c64ffe0ff3"},{"id":"sym:cargo visioncraft . plan/Invocation#validate().","kind":"sequence","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/Invocation#validate().","span":{"start_line":104,"start_col":5,"end_line":137,"end_col":6},"sig_hash":"blake3-16:df6aee1d4a2a9d4b92536e69433d3c6a","body_hash":"blake3-16:49668b9727c1ac54be4cd4c716e96fee","participants":["sym:cargo visioncraft . plan/Invocation#","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":109},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":109},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":110},{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":115},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":114},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":120},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":127},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":129},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":133}],"hash":"blake3:3354fc277d9bd09a45bbea06e5bc7342f7c586064f59d475a64b2bf33d0fda57"},{"id":"sym:cargo visioncraft . plan/QualityPlan#validate().","kind":"sequence","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/QualityPlan#validate().","span":{"start_line":291,"start_col":5,"end_line":398,"end_col":6},"sig_hash":"blake3-16:fa4cb29f8ee4f18407e9aa68bcbe8d75","body_hash":"blake3-16:16e4b5b86916c3ea0a2107386a4cc734","participants":["sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft .","sym:cargo visioncraft . plan/Subject#"],"calls":[{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":296},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":297},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":301},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":301},{"target":"sym:cargo visioncraft . plan/Subject#validate().","confidence":"exact","line":302,"expands":"sym:cargo visioncraft . plan/Subject#validate()."},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":303},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":307},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":317},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":316},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":327},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":331},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":335},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":338},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":346},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":354},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":353},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":362},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":361},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":365},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":365},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":367},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":374},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":380},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":379},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":385},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":391}],"hash":"blake3:a69180a482bd092c9035df0f4320ba289ec9d3162ec8ec2442e80c95752b5e56"}]},{"source":"src/process.rs","document":"src/process.rs.md","module":"sym:cargo visioncraft . process/","source_hash":"blake3:b24b8fb96eba5f197c4a00e8da464df9d6d53b98c4db058f9b684e8da1c64e3c","document_hash":"blake3:c03e83f7bbadfe8920588aef29b50133bac05827f21474b6c72a022d5444671c","fragments":[{"id":"structure:src/process.rs","kind":"structure","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/","span":{"start_line":1,"start_col":1,"end_line":425,"end_col":1},"sig_hash":"blake3-16:7e2098952f191664fce2401b4fe2c94b","body_hash":"blake3-16:9afdf9190af30106c625ee75cfc287b4","participants":["sym:cargo visioncraft . process/","sym:cargo visioncraft . process/CapturedRun#","sym:cargo visioncraft . process/Termination#"],"hash":"blake3:16d6e3cdcb6791ae483d161c57a6207500a8f8ee76e3321bb2e9ed2fb52fdaab"},{"id":"sym:cargo visioncraft . process/run_command_with_env().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/run_command_with_env().","span":{"start_line":225,"start_col":1,"end_line":425,"end_col":2},"sig_hash":"blake3-16:60939e55bba0ee305de92ce58430f493","body_hash":"blake3-16:85047a9f67830cc53472ce1dab56e2c9","participants":["sym:cargo visioncraft . process/","sym:cargo visioncraft . plan/Invocation#","sym:extern nix"],"calls":[{"target":"sym:cargo visioncraft . plan/Invocation#validate().","confidence":"exact","line":253,"expands":"sym:cargo visioncraft . plan/Invocation#validate()."},{"target":"sym:cargo visioncraft . process/unix_now().","confidence":"exact","line":256},{"target":"sym:cargo visioncraft . process/private_file().","confidence":"exact","line":260},{"target":"sym:cargo visioncraft . process/private_file().","confidence":"exact","line":261},{"target":"sym:cargo visioncraft . process/unix_now().","confidence":"exact","line":313},{"target":"sym:cargo visioncraft . process/capture().","confidence":"exact","line":322},{"target":"sym:cargo visioncraft . process/capture().","confidence":"exact","line":330},{"target":"sym:extern nix::unistd::Pid::from_raw","confidence":"external","line":364},{"target":"sym:extern nix::sys::signal::killpg","confidence":"external","line":364},{"target":"sym:cargo visioncraft . process/signal_group().","confidence":"exact","line":384},{"target":"sym:cargo visioncraft . process/signal_group().","confidence":"exact","line":395},{"target":"sym:cargo visioncraft . process/unix_now().","confidence":"exact","line":421}],"hash":"blake3:e8e9bb5dbba17720424498f68a29d37094ccac94fc080f656c80cbde67386d59"}]}]} +{"schema_version":2,"generator":"sealmap-corpus 0.4.0","codebase":"visioncraft","stats":{"files":10,"symbols":168,"relations":632,"flows":80,"calls":543},"documents":[{"source":"src/cli.rs","document":"src/cli.rs.md","module":"sym:cargo visioncraft . cli/","source_hash":"blake3:e5a287dcb11e681724fa694daeace991975ed75a6cc4cf342d3328a778ce0c6d","document_hash":"blake3:c3b266d36b5d8ccc0d932770c364a7e627ea91c044344b40fe7db175a310670d","fragments":[{"id":"structure:src/cli.rs","kind":"structure","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/","span":{"start_line":1,"start_col":1,"end_line":1135,"end_col":1},"sig_hash":"blake3-16:a91e60562b65dab9be5fcfdd480a0025","body_hash":"blake3-16:00bd56919309e773ec512fe9b51e3363","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft . cli/Cli#","sym:cargo visioncraft . cli/CliError#","sym:cargo visioncraft . cli/ContextFile#","sym:cargo visioncraft . cli/EvaluateOptions#","sym:cargo visioncraft . cli/ExpectationCommand#","sym:cargo visioncraft . cli/FamilyDeclaration#","sym:cargo visioncraft . cli/GateCommand#","sym:cargo visioncraft . cli/GitOutput#","sym:cargo visioncraft . cli/InitOptions#","sym:cargo visioncraft . cli/Operation#","sym:cargo visioncraft . cli/PlanCommand#","sym:cargo visioncraft . cli/RunOptions#","sym:cargo visioncraft . cli/SnapshotInput#"],"hash":"blake3:cc028d12f950c3ae1e85c12d11800b79b52157876e4bc9dd1614e6a982724168"},{"id":"sym:cargo visioncraft . cli/confined().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/confined().","span":{"start_line":225,"start_col":1,"end_line":251,"end_col":2},"sig_hash":"blake3-16:0f062b609af0623484ee4a8f3ce0791c","body_hash":"blake3-16:4d6d3d8c0f03abdfbfa2e19fad43f067","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":229},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":230},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":235},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":240},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":248}],"hash":"blake3:10134bbd7624f9bdd4c0c962084ddf99406fd07aaff1c112d8e6fde98e6256d2"},{"id":"sym:cargo visioncraft . cli/read_explicit().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/read_explicit().","span":{"start_line":273,"start_col":1,"end_line":285,"end_col":2},"sig_hash":"blake3-16:0135480ca8cad65a15367671ed65406d","body_hash":"blake3-16:2795f0c0dbe9df2e76d5b564e531760e","participants":["sym:cargo visioncraft . cli/"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":274},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":282},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":283,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":284}],"hash":"blake3:ea44521ca2c9580a30bcd4324260bf263e6d214f80c0579223fe16ef7cab9f86"},{"id":"sym:cargo visioncraft . cli/output_path().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/output_path().","span":{"start_line":287,"start_col":1,"end_line":312,"end_col":2},"sig_hash":"blake3-16:dbdb74d9394b0d29e9e3e8e51c008181","body_hash":"blake3-16:ca6d64c44631f2c0ee6c2ac804186a41","participants":["sym:cargo visioncraft . cli/"],"calls":[{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":296},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":302},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":304},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":306},{"target":"sym:cargo visioncraft . cli/io_error().","confidence":"exact","line":308}],"hash":"blake3:16ae04e0f4143479ef97deccd15f1e0d6c9c12d1f16c3de82ed63430b15466ec"},{"id":"sym:cargo visioncraft . cli/write_new().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/write_new().","span":{"start_line":314,"start_col":1,"end_line":326,"end_col":2},"sig_hash":"blake3-16:2d4d3f36490d72b3f6dc2d027eca4f3e","body_hash":"blake3-16:697a3ac4de3c725a30cfdc25488b8f86","participants":["sym:cargo visioncraft . cli/","sym:extern tempfile"],"calls":[{"target":"sym:cargo visioncraft . cli/output_path().","confidence":"exact","line":315,"expands":"sym:cargo visioncraft . cli/output_path()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":318},{"target":"sym:extern tempfile::NamedTempFile::new_in","confidence":"external","line":319},{"target":"sym:cargo visioncraft . cli/io_error().","confidence":"exact","line":324}],"hash":"blake3:457d2ebe0c5c2371326d12fd034f42e6ec1b554309aa824f919c052357d114df"},{"id":"sym:cargo visioncraft . cli/git().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/git().","span":{"start_line":345,"start_col":1,"end_line":405,"end_col":2},"sig_hash":"blake3-16:4841aa17643eae3fb5fe09d3badd3661","body_hash":"blake3-16:f6010aec4da04480c3e910c072d027ab","participants":["sym:cargo visioncraft . cli/","sym:extern tempfile","sym:cargo visioncraft . git_metadata/","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:extern tempfile::Builder::new","confidence":"external","line":346},{"target":"sym:extern tempfile::Builder::prefix","confidence":"external","line":347},{"target":"sym:extern tempfile::Builder::permissions","confidence":"external","line":351},{"target":"sym:extern tempfile::Builder::tempdir","confidence":"external","line":353},{"target":"sym:cargo visioncraft . git_metadata/prefix().","confidence":"exact","line":359},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":364},{"target":"sym:cargo visioncraft . git_metadata/fixed_environment().","confidence":"exact","line":372},{"target":"sym:cargo visioncraft . process/run_command_with_env().","confidence":"exact","line":383,"expands":"sym:cargo visioncraft . process/run_command_with_env()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":395},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":397},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":398},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":399},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":400}],"hash":"blake3:83e03825a35a5889cc5fdc8f48f354c078f2c26ce2c1f5b2a27c57c91d69ef20"},{"id":"sym:cargo visioncraft . cli/revision().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/revision().","span":{"start_line":407,"start_col":1,"end_line":417,"end_col":2},"sig_hash":"blake3-16:0b6fb7f218212ea850ac236d821d8a54","body_hash":"blake3-16:57f70fb943003d553d789a8ac8afdf57","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":408,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":410},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":413},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":414}],"hash":"blake3:6a47990d6e52a53cd8a184d578ac35266d83543a99f35ac8eb40a6ae358444e3"},{"id":"sym:cargo visioncraft . cli/selected_dirty().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/selected_dirty().","span":{"start_line":419,"start_col":1,"end_line":484,"end_col":2},"sig_hash":"blake3-16:466ae4a23ec9651aa81d4bed047fce21","body_hash":"blake3-16:60c71d02d369ba96d0e8ac250beb706a","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":424,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":426},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":437},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":439},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":445},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":452},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":453},{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":455,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":457},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":460},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":464},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":466},{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":468,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":470},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":472},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":474,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":475},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":479}],"hash":"blake3:453ed573926bd3366697d5f770d078d6675b2d10fc95e5d42b91b2998b8b86df"},{"id":"sym:cargo visioncraft . cli/inputs().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/inputs().","span":{"start_line":493,"start_col":1,"end_line":521,"end_col":2},"sig_hash":"blake3-16:ed0d5f7af2c90806f98bbe55046295b0","body_hash":"blake3-16:a4fe913978641a3fc470a6673895dbdd","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":496,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":499},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":499},{"target":"sym:cargo visioncraft . cli/io_error().","confidence":"exact","line":509},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":511}],"hash":"blake3:3f2dccdf84b13932d2d5f50d867c14fdcb3bccb66ede478c1abcba1fd56cc8a7"},{"id":"sym:cargo visioncraft . cli/source_snapshot().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/source_snapshot().","span":{"start_line":523,"start_col":1,"end_line":557,"end_col":2},"sig_hash":"blake3-16:99ceb13e4265b3151783ffc6a3e45c52","body_hash":"blake3-16:cbf9aee3425988e9536de14608e8da81","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:extern sealmap_corpus"],"calls":[{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":532,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":532},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":535},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":540},{"target":"sym:extern sealmap_corpus::review::Artifact::iter","confidence":"external","line":542},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":545},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":556}],"hash":"blake3:f3d87fe2bf48f895fb27ad21313f2b1c7930ba3db6156c76295df6bb381ab3a4"},{"id":"sym:cargo visioncraft . cli/init().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/init().","span":{"start_line":564,"start_col":1,"end_line":652,"end_col":2},"sig_hash":"blake3-16:b4e883cfce087fb3dfc81327eb4ad912","body_hash":"blake3-16:b5e11d29744c7e97abe293abd262f6ed","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":565},{"target":"sym:cargo visioncraft . cli/output_path().","confidence":"exact","line":566,"expands":"sym:cargo visioncraft . cli/output_path()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":570},{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":573},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":574},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":577,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":578,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/selected_dirty().","confidence":"exact","line":579,"expands":"sym:cargo visioncraft . cli/selected_dirty()."},{"target":"sym:cargo visioncraft . cli/source_snapshot().","confidence":"exact","line":581,"expands":"sym:cargo visioncraft . cli/source_snapshot()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":589},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":594},{"target":"sym:cargo visioncraft . plan/QualityPlan#validate().","confidence":"exact","line":634,"expands":"sym:cargo visioncraft . plan/QualityPlan#validate()."},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":635,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":636,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":637},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":640},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":642},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":643,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":645,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":647},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":647,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":648}],"hash":"blake3:2bd9ae15fbaff3cd2eec8f3f3539d22c3dd9870def20c2e0f278d9303ee76f01"},{"id":"sym:cargo visioncraft . cli/add_artifact().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/add_artifact().","span":{"start_line":654,"start_col":1,"end_line":662,"end_col":2},"sig_hash":"blake3-16:f0e71327596608de7e6b1f6a54853e2d","body_hash":"blake3-16:9b18aea04b32a8ac770134c2c7b25309","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . evidence/VerifiedArtifacts#"],"calls":[{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":659},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":660,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":660},{"target":"sym:cargo visioncraft . evidence/VerifiedArtifacts#insert().","confidence":"exact","line":661}],"hash":"blake3:9ab7e24505a5f71cd2e61508e0fabb0e233106589d756559b7851f0b72d83d88"},{"id":"sym:cargo visioncraft . cli/evidence_parent().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/evidence_parent().","span":{"start_line":674,"start_col":1,"end_line":685,"end_col":2},"sig_hash":"blake3-16:db2e97ad57784510b3ed00e2d46b651b","body_hash":"blake3-16:88b1ddfbb57f2b8c7f2a5d0b9bb1ffb9","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":675},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":676},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":682},{"target":"sym:cargo visioncraft . cli/output_path().","confidence":"exact","line":684,"expands":"sym:cargo visioncraft . cli/output_path()."}],"hash":"blake3:7a67d1cb03b3bb52a8fe9d0834e11961466acafa8c8c2ffb261312621ece5f52"},{"id":"sym:cargo visioncraft . cli/run().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/run().","span":{"start_line":759,"start_col":1,"end_line":915,"end_col":2},"sig_hash":"blake3-16:ba17c27738cfde5ad2571ad58ca94d50","body_hash":"blake3-16:08da835ef954e7dd9cc676a5efc8ef47","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . process/","sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft . evidence/ExecutionReceipt#"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":760},{"target":"sym:cargo visioncraft . cli/read_plan().","confidence":"exact","line":761},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":768},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":772},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":777,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":780,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":781,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":783},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":790,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":790},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":791},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":792},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":796},{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":797},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":798,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":799},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":799,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/evidence_parent().","confidence":"exact","line":801,"expands":"sym:cargo visioncraft . cli/evidence_parent()."},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":801,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":806,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":807,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":809},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":814,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":817},{"target":"sym:cargo visioncraft . cli/executable().","confidence":"exact","line":818},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":823},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":830},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":831},{"target":"sym:cargo visioncraft . process/run_command().","confidence":"exact","line":837},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":841},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":841},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":845},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":845},{"target":"sym:cargo visioncraft . cli/process_status().","confidence":"exact","line":847},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":853,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . plan/QualityPlan#digest().","confidence":"inferred","line":872},{"target":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","confidence":"exact","line":896,"expands":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":898},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":898,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/execution_exit().","confidence":"exact","line":899},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":911}],"hash":"blake3:f85f4c799e989e52e1d019de0ab972275cb43e5195f141cb2ea2d324af9bb903"},{"id":"sym:cargo visioncraft . cli/load_receipts().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/load_receipts().","span":{"start_line":917,"start_col":1,"end_line":947,"end_col":2},"sig_hash":"blake3-16:c5944f1ef230b917228e3114fc3f9133","body_hash":"blake3-16:8e82d035d63b0fd789327e31b5b9794c","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft . evidence/ExecutionReceipt#"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":921},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":928},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":933,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":940},{"target":"sym:cargo visioncraft . evidence/ExecutionReceipt#parse().","confidence":"exact","line":940},{"target":"sym:cargo visioncraft . cli/receipt_artifacts().","confidence":"exact","line":941},{"target":"sym:cargo visioncraft . cli/add_artifact().","confidence":"exact","line":942,"expands":"sym:cargo visioncraft . cli/add_artifact()."}],"hash":"blake3:cc786ac0e563e162c5bd861f9c216fe9ef10f557e6eeb37a0b004e691b4aa023"},{"id":"sym:cargo visioncraft . cli/evaluate_options().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/evaluate_options().","span":{"start_line":949,"start_col":1,"end_line":1094,"end_col":2},"sig_hash":"blake3-16:e24a4e8e44d00858f88e500a666ef939","body_hash":"blake3-16:9fd6438f6c66bc74969f7f025e4aabb5","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . plan/Subject#","sym:cargo visioncraft . evidence/VerifiedArtifacts#","sym:cargo visioncraft . cli/ContextFile#","sym:cargo visioncraft . evaluate/EvaluationContext#","sym:extern sealmap_corpus","sym:cargo visioncraft . evaluate/","sym:extern serde_json"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":950},{"target":"sym:cargo visioncraft . cli/read_plan().","confidence":"exact","line":951},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":954,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":955,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":958},{"target":"sym:cargo visioncraft . cli/selected_dirty().","confidence":"exact","line":963,"expands":"sym:cargo visioncraft . cli/selected_dirty()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":967},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":967},{"target":"sym:cargo visioncraft . cli/read_explicit().","confidence":"exact","line":973,"expands":"sym:cargo visioncraft . cli/read_explicit()."},{"target":"sym:cargo visioncraft . from_json().","confidence":"exact","line":974},{"target":"sym:cargo visioncraft . plan/Subject#validate().","confidence":"exact","line":975,"expands":"sym:cargo visioncraft . plan/Subject#validate()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":980},{"target":"sym:cargo visioncraft . evidence/VerifiedArtifacts#default().","confidence":"inferred","line":991},{"target":"sym:cargo visioncraft . cli/load_receipts().","confidence":"exact","line":994,"expands":"sym:cargo visioncraft . cli/load_receipts()."},{"target":"sym:cargo visioncraft . cli/ContextFile#default().","confidence":"inferred","line":996},{"target":"sym:cargo visioncraft . cli/read_explicit().","confidence":"exact","line":998,"expands":"sym:cargo visioncraft . cli/read_explicit()."},{"target":"sym:cargo visioncraft . from_json().","confidence":"exact","line":999},{"target":"sym:cargo visioncraft . cli/add_artifact().","confidence":"exact","line":1006,"expands":"sym:cargo visioncraft . cli/add_artifact()."},{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":1011,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . evaluate/EvaluationContext#new().","confidence":"exact","line":1026},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":1033},{"target":"sym:extern sealmap_corpus::route::Family::named","confidence":"external","line":1039},{"target":"sym:cargo visioncraft . evaluate/","confidence":"exact","line":1043},{"target":"sym:extern serde_json::to_value","confidence":"external","line":1050},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":1057}],"hash":"blake3:17642162233672dd735dae4ee72a7a222c770a69d34827a8c3af548eac157f76"},{"id":"sym:cargo visioncraft . cli/execute().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/execute().","span":{"start_line":1096,"start_col":1,"end_line":1135,"end_col":2},"sig_hash":"blake3-16:46912e87ff2e1ea76267f5fc634b601d","body_hash":"blake3-16:38f8733b2f66f86957663943eeb3898d","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft . deepsec/"],"calls":[{"target":"sym:cargo visioncraft . cli/init().","confidence":"exact","line":1105,"expands":"sym:cargo visioncraft . cli/init()."},{"target":"sym:cargo visioncraft . cli/read_plan().","confidence":"exact","line":1109},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":1111},{"target":"sym:cargo visioncraft . cli/run().","confidence":"exact","line":1123,"expands":"sym:cargo visioncraft . cli/run()."},{"target":"sym:cargo visioncraft . cli/evaluate_options().","confidence":"exact","line":1130,"expands":"sym:cargo visioncraft . cli/evaluate_options()."},{"target":"sym:cargo visioncraft . deepsec/execute().","confidence":"exact","line":1132,"expands":"sym:cargo visioncraft . deepsec/execute()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":1132}],"hash":"blake3:b33cd48ba99d0f8f35cf65973f7f754430fcf32c4df4237059c40674dbd2c4ce"}]},{"source":"src/deepsec.rs","document":"src/deepsec.rs.md","module":"sym:cargo visioncraft . deepsec/","source_hash":"blake3:f6a856414c586500e5bbcb69b8f4cee3caf40b2de0b8895792ad0ca34e45c977","document_hash":"blake3:ec097a9ceb33b6c3d8ac060a9854d8d96d05148616c6fb10a562fc98639c5423","fragments":[{"id":"structure:src/deepsec.rs","kind":"structure","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/","span":{"start_line":1,"start_col":1,"end_line":1063,"end_col":1},"sig_hash":"blake3-16:dfca6b22e7a0f75576ee19430ce800ad","body_hash":"blake3-16:cd635cb8681ff032b09a653c3982a09e","participants":["sym:cargo visioncraft . deepsec/","sym:cargo visioncraft . deepsec/Attempt#","sym:cargo visioncraft . deepsec/DeepsecOptions#","sym:cargo visioncraft . deepsec/DeepsecPolicy#","sym:cargo visioncraft . deepsec/GateError#","sym:cargo visioncraft . deepsec/StrictJson#"],"hash":"blake3:6eecc34c285fec9c493ea0145ea40bfa7badb172c994b1257ff76b6d5cbb9329"},{"id":"sym:cargo visioncraft . deepsec/DeepsecPolicy#validate().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/DeepsecPolicy#validate().","span":{"start_line":142,"start_col":5,"end_line":229,"end_col":6},"sig_hash":"blake3-16:8e9590b4e5ea930dbb967d625e57fb57","body_hash":"blake3-16:0aaf1b920c2175079b0541e62429279d","participants":["sym:cargo visioncraft . deepsec/DeepsecPolicy#","sym:cargo visioncraft . deepsec/","sym:extern url"],"calls":[{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":146},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":149},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":152},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":155},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":161},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":167},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":180},{"target":"sym:extern url::Url::parse","confidence":"external","line":183},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":184},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":192},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":200},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":206},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":216},{"target":"sym:cargo visioncraft . deepsec/duration_ms().","confidence":"exact","line":223},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":224}],"hash":"blake3:abe7fa45bd5abad24561011927a3cf90fe983f66bed974955fbc0f150c2a401a"},{"id":"sym:cargo visioncraft . deepsec/findings().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/findings().","span":{"start_line":371,"start_col":1,"end_line":410,"end_col":2},"sig_hash":"blake3-16:d958a149d303f700360dacf89d848981","body_hash":"blake3-16:d23d0fceb0331f95373edce172a94932","participants":["sym:cargo visioncraft . deepsec/","sym:extern serde_json"],"calls":[{"target":"sym:extern serde_json::from_slice","confidence":"external","line":372},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":373},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":378},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":388},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":395},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":402},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":405}],"hash":"blake3:730cdc58cc3f43348c0dce498d29c1d82277e0e08fec90504dd8015cc12953c5"},{"id":"sym:cargo visioncraft . deepsec/Attempt#command().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/Attempt#command().","span":{"start_line":484,"start_col":5,"end_line":559,"end_col":6},"sig_hash":"blake3-16:e8c318eaf968b6ab917a2c6d444e8f2e","body_hash":"blake3-16:4aa6ec82fcec8f10bf66efbf85f15248","participants":["sym:cargo visioncraft . deepsec/Attempt#","sym:cargo visioncraft . deepsec/","sym:cargo visioncraft . process/","sym:cargo visioncraft . git_metadata/","sym:extern serde_json"],"calls":[{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":497},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":500},{"target":"sym:cargo visioncraft . git_metadata/prefix().","confidence":"exact","line":502},{"target":"sym:cargo visioncraft . git_metadata/fixed_environment().","confidence":"exact","line":507},{"target":"sym:cargo visioncraft . deepsec/environment().","confidence":"exact","line":510},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":522},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":523},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":520},{"target":"sym:cargo visioncraft . process/run_command_with_env().","confidence":"exact","line":525,"expands":"sym:cargo visioncraft . process/run_command_with_env()."},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":527},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":528},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":539},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":540},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":537},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":545},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":548},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":549},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":553},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":557}],"hash":"blake3:217704a889e0dea86a0b3a481dc04ae14029e0b4c6895a34f03be84c965d8db4"},{"id":"sym:cargo visioncraft . deepsec/execute().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/execute().","span":{"start_line":618,"start_col":1,"end_line":1025,"end_col":2},"sig_hash":"blake3-16:0ba905b365d196f55d4ed680e35ea604","body_hash":"blake3-16:a139be56c5a4af8b6e650f9352bf23f8","participants":["sym:cargo visioncraft . deepsec/","sym:cargo visioncraft .","sym:cargo visioncraft . deepsec/DeepsecPolicy#","sym:extern serde_json","sym:cargo visioncraft . process/","sym:extern tempfile","sym:cargo visioncraft . deepsec/Attempt#","sym:extern recorded"],"calls":[{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":635},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":640},{"target":"sym:cargo visioncraft . from_json().","confidence":"exact","line":645},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":646},{"target":"sym:cargo visioncraft . deepsec/DeepsecPolicy#[Default]default().","confidence":"exact","line":647},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":666},{"target":"sym:cargo visioncraft . deepsec/root_for().","confidence":"exact","line":671},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":679},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":680},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":681},{"target":"sym:extern serde_json::to_string_pretty","confidence":"external","line":742},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":743},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":751},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":758},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":760},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":762},{"target":"sym:cargo visioncraft . deepsec/workspace_lock().","confidence":"exact","line":766},{"target":"sym:cargo visioncraft . deepsec/validate_workspace_tree().","confidence":"exact","line":767},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":769},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":771},{"target":"sym:cargo visioncraft . process/private_file().","confidence":"exact","line":772},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":775},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":776},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":773},{"target":"sym:extern tempfile::NamedTempFile::new_in","confidence":"external","line":778},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":782},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":785},{"target":"sym:extern serde_json::to_string_pretty","confidence":"external","line":791},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":792},{"target":"sym:extern tempfile::NamedTempFile::new_in","confidence":"external","line":794},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":799},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":812,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/supported_version().","confidence":"exact","line":832},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":833},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":838,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":849,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:extern recorded::select","confidence":"external","line":860},{"target":"sym:extern recorded::snapshot","confidence":"external","line":861},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":864},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":865},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":862},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":868},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":895,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":897},{"target":"sym:extern recorded::pending","confidence":"external","line":906},{"target":"sym:extern recorded::run_files","confidence":"external","line":910},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":927,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":929},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":932},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":935},{"target":"sym:extern recorded::snapshot","confidence":"external","line":940},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":943},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":944},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":941},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":947},{"target":"sym:extern recorded::validate_review","confidence":"external","line":949},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":969,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":971},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":973},{"target":"sym:cargo visioncraft . deepsec/findings().","confidence":"exact","line":974,"expands":"sym:cargo visioncraft . deepsec/findings()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":976},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":1015},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":1016},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":1013},{"target":"sym:extern serde_json::to_string_pretty","confidence":"external","line":1020},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":1021}],"hash":"blake3:e9b4f12a5bac11d760ae501ea05d3f3c81a0b569e93bdae46dd99b6f02ab5b2d"}]},{"source":"src/deepsec_evidence.rs","document":"src/deepsec_evidence.rs.md","module":"sym:cargo visioncraft . deepsec_evidence/","source_hash":"blake3:f26a627cb792b2b78f7637d38ad80a0e0260b566505bedf92cd524d64dd5a0ac","document_hash":"blake3:c9746c40e975c666b5eb5fb7d23018c83c87b179a6d625a52ef3903f5ec8ccb8","fragments":[{"id":"structure:src/deepsec_evidence.rs","kind":"structure","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/","span":{"start_line":1,"start_col":1,"end_line":317,"end_col":1},"sig_hash":"blake3-16:d29639f733f43b721a769946fd5c16ea","body_hash":"blake3-16:5c6b431f7b9b75878e334ded4e0529f8","participants":["sym:cargo visioncraft . deepsec_evidence/"],"hash":"blake3:2b62a4deed164da5864a4a3b4a5e4bcd5cf0545d80b644f32199c4c096571d9d"},{"id":"sym:cargo visioncraft . deepsec_evidence/confined().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/confined().","span":{"start_line":15,"start_col":1,"end_line":37,"end_col":2},"sig_hash":"blake3-16:339a3f31cc29d571f0d49cac65efa8cf","body_hash":"blake3-16:bfc51a62ae369d14245e4fe1e398ad60","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:cargo visioncraft .","sym:extern visioncraft"],"calls":[{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":16},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":20},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":29},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":33}],"hash":"blake3:b8c9c4216ed7327069ac7d1d1e50af8df2c6387d1660f7931168280d9a740822"},{"id":"sym:cargo visioncraft . deepsec_evidence/snapshot().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/snapshot().","span":{"start_line":38,"start_col":1,"end_line":60,"end_col":2},"sig_hash":"blake3-16:f9fca86ed05e6dea51f36aa77af98298","body_hash":"blake3-16:92e1f22220e61aed17b21bca7709b198","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft","sym:cargo visioncraft ."],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":40},{"target":"sym:cargo visioncraft . deepsec_evidence/confined().","confidence":"exact","line":46,"expands":"sym:cargo visioncraft . deepsec_evidence/confined()."},{"target":"sym:extern visioncraft::read_bounded","confidence":"inferred","line":46},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":49},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":56}],"hash":"blake3:5653bc15ccdd69ddf29a8b3373e42cc5d25cac283259f0cef32cb2a6d5713278"},{"id":"sym:cargo visioncraft . deepsec_evidence/select().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/select().","span":{"start_line":61,"start_col":1,"end_line":169,"end_col":2},"sig_hash":"blake3-16:cc9a89e8f0905b3cb12ddfe8572273b4","body_hash":"blake3-16:a235aab603da0aabd165ee2efd5dc868","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft"],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":71},{"target":"sym:extern visioncraft::read_bounded","confidence":"inferred","line":75},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":103},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":111},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":126},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":132},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":140},{"target":"sym:cargo visioncraft . deepsec_evidence/confined().","confidence":"exact","line":146,"expands":"sym:cargo visioncraft . deepsec_evidence/confined()."},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":160},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":162}],"hash":"blake3:5bb9a75aa00caea45c6e4b56b2814cf5c9c73123ebbc47fc505690ae8c94d101"},{"id":"sym:cargo visioncraft . deepsec_evidence/run_files().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/run_files().","span":{"start_line":170,"start_col":1,"end_line":193,"end_col":2},"sig_hash":"blake3-16:6da82f7f40f25f96425a127fb162af24","body_hash":"blake3-16:f7cb0af119c19b3933742680610ae1da","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft"],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":176},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":178},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":181},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":182},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":184}],"hash":"blake3:1624786ac1edaf9933c59e02458c9e8a45069628a872c991e089a8730adc656e"},{"id":"sym:cargo visioncraft . deepsec_evidence/validate_review().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/validate_review().","span":{"start_line":220,"start_col":1,"end_line":317,"end_col":2},"sig_hash":"blake3-16:48c209a2019e0cdfb19ce0ddd22d8346","body_hash":"blake3-16:bdc3f563f8b939e53ba3780bfde17d48","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern sealmap_corpus","sym:extern serde_json","sym:extern visioncraft","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . deepsec_evidence/run_files().","confidence":"exact","line":229,"expands":"sym:cargo visioncraft . deepsec_evidence/run_files()."},{"target":"sym:cargo visioncraft . deepsec_evidence/object().","confidence":"exact","line":230},{"target":"sym:extern sealmap_corpus::review::Artifact::iter","confidence":"external","line":236},{"target":"sym:cargo visioncraft . deepsec_evidence/file_record().","confidence":"exact","line":240},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":247},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":248},{"target":"sym:extern visioncraft::write_new","confidence":"inferred","line":249},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":251},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":256},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":257},{"target":"sym:extern sealmap_corpus::review::Artifact::len","confidence":"external","line":262},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":264},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":276},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":283},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":286},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":297},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":308}],"hash":"blake3:ae2141692794b47fd4e101b62646dbe9a0868370fb4b96e96f8a8df88584ea13"}]},{"source":"src/evaluate.rs","document":"src/evaluate.rs.md","module":"sym:cargo visioncraft . evaluate/","source_hash":"blake3:68c30067ced8712ddcf6cb6c32ff742f62c952f39d3d4fa57951fe599b7da94c","document_hash":"blake3:aec7081440aea0a482049a8ca67278c55d75fae2f7815adcbc1faa6b97987d87","fragments":[{"id":"structure:src/evaluate.rs","kind":"structure","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/","span":{"start_line":1,"start_col":1,"end_line":657,"end_col":1},"sig_hash":"blake3-16:9fe9b147ca2d959744dccbc9bb23ac64","body_hash":"blake3-16:6fe55723dc753cb595c465a48957545a","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft . evaluate/CheckOutcome#","sym:cargo visioncraft . evaluate/CheckReport#","sym:cargo visioncraft . evaluate/EvaluationContext#","sym:cargo visioncraft . evaluate/ExpectationReport#","sym:cargo visioncraft . evaluate/GateOutcome#","sym:cargo visioncraft . evaluate/GateReport#"],"hash":"blake3:d5091dfff7bb58c6eb3e49cacb4b5589dcaf0e603efe16f2f4b6f4f74c0df81b"},{"id":"sym:cargo visioncraft . evaluate/check_receipt().","kind":"sequence","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/check_receipt().","span":{"start_line":160,"start_col":1,"end_line":273,"end_col":2},"sig_hash":"blake3-16:ee70d752233f4499288b800fcec0a414","body_hash":"blake3-16:d1fb01a0dcd74e443f9c5104f4378bc0","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft . evidence/ExecutionReceipt#","sym:cargo visioncraft . plan/","sym:cargo visioncraft . evidence/VerifiedArtifacts#"],"calls":[{"target":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","confidence":"exact","line":168,"expands":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate()."},{"target":"sym:cargo visioncraft . plan/same_inputs().","confidence":"exact","line":177},{"target":"sym:cargo visioncraft . evaluate/context_limits().","confidence":"exact","line":183},{"target":"sym:cargo visioncraft . evaluate/age_limit().","confidence":"exact","line":184},{"target":"sym:cargo visioncraft . evidence/VerifiedArtifacts#byte_len().","confidence":"inferred","line":211}],"hash":"blake3:03deb8052d7f7256279b5dd683bac32c7d37e95026d1630b4e041a7b51e85f0e"},{"id":"sym:cargo visioncraft . evaluate/assessment_binding().","kind":"sequence","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/assessment_binding().","span":{"start_line":298,"start_col":1,"end_line":320,"end_col":2},"sig_hash":"blake3-16:e2d6db985ebd381da5d83e24ce107563","body_hash":"blake3-16:7b52282e846da93f2cde20af7045a03b","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":307},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":311},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":312},{"target":"sym:cargo visioncraft . evaluate/age_limit().","confidence":"exact","line":317},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":316}],"hash":"blake3:30162b56ccfa772885e62b9a777b4781fbd01a3957b7eb431ef2feb04c8d50e9"},{"id":"sym:cargo visioncraft . evaluate/expectation_report().","kind":"sequence","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/expectation_report().","span":{"start_line":322,"start_col":1,"end_line":524,"end_col":2},"sig_hash":"blake3-16:60bd522cd3ba06f3d9da1f7b3e90b52b","body_hash":"blake3-16:e4d1797b13f584d6f345f1601b1187e9","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft .","sym:extern sealmap_corpus"],"calls":[{"target":"sym:cargo visioncraft . evaluate/referenced_check().","confidence":"exact","line":333},{"target":"sym:cargo visioncraft . evaluate/referenced_check().","confidence":"exact","line":336},{"target":"sym:cargo visioncraft . evaluate/referenced_check().","confidence":"exact","line":339},{"target":"sym:cargo visioncraft . evaluate/assessment_binding().","confidence":"exact","line":371,"expands":"sym:cargo visioncraft . evaluate/assessment_binding()."},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":381},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":382},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":383},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":380},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":386},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":391},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":400},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":404},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":411},{"target":"sym:extern sealmap_corpus::route::cross_family_with","confidence":"external","line":421},{"target":"sym:cargo visioncraft . evaluate/assessment_binding().","confidence":"exact","line":479,"expands":"sym:cargo visioncraft . evaluate/assessment_binding()."},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":490},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":490},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":489}],"hash":"blake3:621bb154f0bc58def0d9b99839bfb5f7f07500da87de83f718956d20bb7d43f5"}]},{"source":"src/evidence.rs","document":"src/evidence.rs.md","module":"sym:cargo visioncraft . evidence/","source_hash":"blake3:edfe990a885f2bcad685855fe0c87e11878174d676e4414f4f9448e818ca520a","document_hash":"blake3:92db7d2db5b346b252f2fd1d9472793cfc0dda06b4ac5f891e0e98a8629fc804","fragments":[{"id":"structure:src/evidence.rs","kind":"structure","document":"src/evidence.rs.md","symbol":"sym:cargo visioncraft . evidence/","span":{"start_line":1,"start_col":1,"end_line":292,"end_col":1},"sig_hash":"blake3-16:af11808614b221a0d9791b5c9c0aa422","body_hash":"blake3-16:07ca5c0150b9e722b1428c85557ebe66","participants":["sym:cargo visioncraft . evidence/","sym:cargo visioncraft . evidence/Actor#","sym:cargo visioncraft . evidence/AuditReceipt#","sym:cargo visioncraft . evidence/AuditVerdict#","sym:cargo visioncraft . evidence/ExecutionReceipt#","sym:cargo visioncraft . evidence/ManualObservation#","sym:cargo visioncraft . evidence/ProcessStatus#","sym:cargo visioncraft . evidence/ReportedResult#","sym:cargo visioncraft . evidence/VerifiedArtifacts#"],"hash":"blake3:4cac75df033fe3d821a9d0b2c1862cba2880e53086a68efdbae14c83e5830ef8"},{"id":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","kind":"sequence","document":"src/evidence.rs.md","symbol":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","span":{"start_line":107,"start_col":5,"end_line":178,"end_col":6},"sig_hash":"blake3-16:ba67f81a1ab12cfa2f20da686b32f5f9","body_hash":"blake3-16:85e6fc9a46be325577dbc0b80d49e394","participants":["sym:cargo visioncraft . evidence/ExecutionReceipt#","sym:cargo visioncraft .","sym:cargo visioncraft . plan/Subject#","sym:cargo visioncraft . plan/Invocation#","sym:cargo visioncraft . plan/"],"calls":[{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":113},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":115},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":115},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":114},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":118},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":118},{"target":"sym:cargo visioncraft . plan/Subject#validate().","confidence":"exact","line":119,"expands":"sym:cargo visioncraft . plan/Subject#validate()."},{"target":"sym:cargo visioncraft . plan/Invocation#validate().","confidence":"exact","line":120,"expands":"sym:cargo visioncraft . plan/Invocation#validate()."},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":122},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":121},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":126},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":126},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":129},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":129},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":131},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":135},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":140},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":144},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":149},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":155},{"target":"sym:cargo visioncraft . plan/validate_input_paths().","confidence":"exact","line":157},{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":161},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":160},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":167},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":166},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":172},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":172},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":171},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":175}],"hash":"blake3:5d5543a5441c2972246e77d27188c7df4e53e2c8f859470ae0c0453e4c16b416"}]},{"source":"src/git_metadata.rs","document":"src/git_metadata.rs.md","module":"sym:cargo visioncraft . git_metadata/","source_hash":"blake3:36f06c2d0b9d416dc106fd7d20839a5fc424fa52dc1e40f572a1acb24050a467","document_hash":"blake3:46ca7ecba1f564098b57d4959fc54fd9ba85ae570aa82e50f7a56a58fc15da66","fragments":[{"id":"structure:src/git_metadata.rs","kind":"structure","document":"src/git_metadata.rs.md","symbol":"sym:cargo visioncraft . git_metadata/","span":{"start_line":1,"start_col":1,"end_line":30,"end_col":1},"sig_hash":"blake3-16:c95500707a557a0575618bc2539225f2","body_hash":"blake3-16:f31363b4d21a99321ffe2494091f132f","participants":["sym:cargo visioncraft . git_metadata/"],"hash":"blake3:80a57b7bae6a450ff5c782a4d5b03d35b571a7e7dfa2d7c7a9266be730c4f555"}]},{"source":"src/lib.rs","document":"src/lib.rs.md","module":"sym:cargo visioncraft .","source_hash":"blake3:bd0cbb39c4723d919330852c9a157a2284d5b8102817d2c74eb7dd89a715bffb","document_hash":"blake3:a2cf789c4c08e0dc3d6f4a053570d75dc8cfd0cb2d49021eeec4364ad51fa0e3","fragments":[{"id":"structure:src/lib.rs","kind":"structure","document":"src/lib.rs.md","symbol":"sym:cargo visioncraft .","span":{"start_line":1,"start_col":1,"end_line":132,"end_col":1},"sig_hash":"blake3-16:ef5f0989f89148798c9d4374da243656","body_hash":"blake3-16:07498bcaf3ef330f07f8945432f31636","participants":["sym:cargo visioncraft .","sym:cargo visioncraft . ContractError#"],"hash":"blake3:9f5d5b04a6ee671ff43fa2cda20f9bd1e2116468c93c310aafc175d99a64ccc4"}]},{"source":"src/main.rs","document":"src/main.rs.md","module":"sym:cargo visioncraft_main .","source_hash":"blake3:4bb59bf863aec89c7e0f6ea0dc232c477e58b0d54775b003a29d43b892e22326","document_hash":"blake3:74400fa28d70e441bfb8d12dd9804989463f276c65f910faed90e827f7563fb8","fragments":[{"id":"structure:src/main.rs","kind":"structure","document":"src/main.rs.md","symbol":"sym:cargo visioncraft_main .","span":{"start_line":1,"start_col":1,"end_line":39,"end_col":1},"sig_hash":"blake3-16:be7e0aa42067d3874629adeff2b5a523","body_hash":"blake3-16:fc2e76f655eeaf6fb63b94d01fdf8e29","participants":["sym:cargo visioncraft_main ."],"hash":"blake3:6072a92081ad96885a435ab18fa15f7156552c9f5a91ffd3b893d30664f7c127"}]},{"source":"src/plan.rs","document":"src/plan.rs.md","module":"sym:cargo visioncraft . plan/","source_hash":"blake3:a0eaf6b6e34139a3b02ddc3d521d69dc4c064884b96dfe85585b1a1e7da2107d","document_hash":"blake3:52a11da34333ac5b351ee8aecb9f323047782e5c9a5a9c3d35b3707c159fa8f8","fragments":[{"id":"structure:src/plan.rs","kind":"structure","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/","span":{"start_line":1,"start_col":1,"end_line":413,"end_col":1},"sig_hash":"blake3-16:a24f0f42e161b5767c66583d880ff1c1","body_hash":"blake3-16:244666ed06402316b2c9d9f1e3d97726","participants":["sym:cargo visioncraft . plan/","sym:cargo visioncraft . plan/CheckSpec#","sym:cargo visioncraft . plan/Evaluator#","sym:cargo visioncraft . plan/EvidenceCategory#","sym:cargo visioncraft . plan/Expectation#","sym:cargo visioncraft . plan/GatePolicy#","sym:cargo visioncraft . plan/Invocation#","sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft . plan/Stabilizer#","sym:cargo visioncraft . plan/Subject#"],"hash":"blake3:c3b2d48210fcb0809c8dffe5957419f886988159fb60f056c51dd599ada41860"},{"id":"sym:cargo visioncraft . plan/Subject#validate().","kind":"sequence","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/Subject#validate().","span":{"start_line":36,"start_col":5,"end_line":58,"end_col":6},"sig_hash":"blake3-16:cc5a01905f372f11d7204d0e8ae9b415","body_hash":"blake3-16:5c8417ac75b7f4969f36b4094d1bba88","participants":["sym:cargo visioncraft . plan/Subject#","sym:cargo visioncraft .","sym:cargo visioncraft . plan/"],"calls":[{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":41},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":41},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":43},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":42},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":47},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":46},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":50},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":55},{"target":"sym:cargo visioncraft . plan/validate_inputs().","confidence":"exact","line":57}],"hash":"blake3:322d9507a0187eaa308b3d532d47b123850c5a0d98d5ae483d9298c64ffe0ff3"},{"id":"sym:cargo visioncraft . plan/Invocation#validate().","kind":"sequence","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/Invocation#validate().","span":{"start_line":104,"start_col":5,"end_line":137,"end_col":6},"sig_hash":"blake3-16:df6aee1d4a2a9d4b92536e69433d3c6a","body_hash":"blake3-16:49668b9727c1ac54be4cd4c716e96fee","participants":["sym:cargo visioncraft . plan/Invocation#","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":109},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":109},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":110},{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":115},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":114},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":120},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":127},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":129},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":133}],"hash":"blake3:3354fc277d9bd09a45bbea06e5bc7342f7c586064f59d475a64b2bf33d0fda57"},{"id":"sym:cargo visioncraft . plan/QualityPlan#validate().","kind":"sequence","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/QualityPlan#validate().","span":{"start_line":291,"start_col":5,"end_line":398,"end_col":6},"sig_hash":"blake3-16:fa4cb29f8ee4f18407e9aa68bcbe8d75","body_hash":"blake3-16:16e4b5b86916c3ea0a2107386a4cc734","participants":["sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft .","sym:cargo visioncraft . plan/Subject#"],"calls":[{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":296},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":297},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":301},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":301},{"target":"sym:cargo visioncraft . plan/Subject#validate().","confidence":"exact","line":302,"expands":"sym:cargo visioncraft . plan/Subject#validate()."},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":303},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":307},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":317},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":316},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":327},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":331},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":335},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":338},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":346},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":354},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":353},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":362},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":361},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":365},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":365},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":367},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":374},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":380},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":379},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":385},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":391}],"hash":"blake3:a69180a482bd092c9035df0f4320ba289ec9d3162ec8ec2442e80c95752b5e56"}]},{"source":"src/process.rs","document":"src/process.rs.md","module":"sym:cargo visioncraft . process/","source_hash":"blake3:aba99dafa4cb40a2a286eaa16908067cf850cba5953360fec3b16569bfff0d28","document_hash":"blake3:ea889a787c6d96c8556deb1e8b85275600fd3920439168157dbb0b41aded78fa","fragments":[{"id":"structure:src/process.rs","kind":"structure","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/","span":{"start_line":1,"start_col":1,"end_line":727,"end_col":1},"sig_hash":"blake3-16:7e2098952f191664fce2401b4fe2c94b","body_hash":"blake3-16:613e44753e01981ef23d4559ae0ecf20","participants":["sym:cargo visioncraft . process/","sym:cargo visioncraft . process/CapturedRun#","sym:cargo visioncraft . process/Termination#","sym:cargo visioncraft . process/linux_proc/"],"hash":"blake3:16d6e3cdcb6791ae483d161c57a6207500a8f8ee76e3321bb2e9ed2fb52fdaab"},{"id":"sym:cargo visioncraft . process/group_running().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/group_running().","span":{"start_line":205,"start_col":1,"end_line":227,"end_col":2},"sig_hash":"blake3-16:450aa867c587af8c528981007e87506e","body_hash":"blake3-16:55cd57e12ea1170ff028ca7b1deaf230","participants":["sym:cargo visioncraft . process/","sym:extern nix","sym:cargo visioncraft . process/linux_proc/"],"calls":[{"target":"sym:extern nix::unistd::Pid::from_raw","confidence":"external","line":213},{"target":"sym:extern nix::sys::signal::killpg","confidence":"external","line":213},{"target":"sym:cargo visioncraft . process/group_probe().","confidence":"exact","line":213},{"target":"sym:cargo visioncraft . process/linux_proc/group_running().","confidence":"exact","line":219,"expands":"sym:cargo visioncraft . process/linux_proc/group_running()."}],"hash":"blake3:160b1938d01776868bd9ac1e251b2293252b7cbbffe4840e44f74fc947cbcc8b"},{"id":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","span":{"start_line":330,"start_col":5,"end_line":338,"end_col":6},"sig_hash":"blake3-16:49458981d13cf9ce4c6c0a96ca26feec","body_hash":"blake3-16:f2879a39f584e155dc13e267a52ae2ef","participants":["sym:cargo visioncraft . process/linux_proc/","sym:extern nix","sym:extern io"],"calls":[{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":332},{"target":"sym:extern nix::unistd::Pid::from_raw","confidence":"external","line":331},{"target":"sym:extern nix::unistd::getpgid","confidence":"external","line":331},{"target":"sym:extern io::Error::from","confidence":"external","line":336}],"hash":"blake3:a798cd074970aad872574e1501ad3536ce7cd6d6435fcfd5a05010cc94c05bd3"},{"id":"sym:cargo visioncraft . process/linux_proc/tasks_dead().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/linux_proc/tasks_dead().","span":{"start_line":340,"start_col":5,"end_line":360,"end_col":6},"sig_hash":"blake3-16:a9f9ab596bca87189a028b260242a28e","body_hash":"blake3-16:123a9041f4c2fbded78b9b11120156c3","participants":["sym:cargo visioncraft . process/linux_proc/"],"calls":[{"target":"sym:cargo visioncraft . process/linux_proc/ids().","confidence":"exact","line":341},{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":343},{"target":"sym:cargo visioncraft . process/linux_proc/bounded_read().","confidence":"exact","line":346},{"target":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","confidence":"exact","line":349,"expands":"sym:cargo visioncraft . process/linux_proc/no_longer_member()."},{"target":"sym:cargo visioncraft . process/linux_proc/state().","confidence":"exact","line":355},{"target":"sym:cargo visioncraft . process/linux_proc/dead().","confidence":"exact","line":355}],"hash":"blake3:d005e864bcd330ec387e43270ff69774f1c4919c5f6b84ab27bcd66989a7fc36"},{"id":"sym:cargo visioncraft . process/linux_proc/dead_members().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/linux_proc/dead_members().","span":{"start_line":362,"start_col":5,"end_line":396,"end_col":6},"sig_hash":"blake3-16:3b267a99719de21556fd8c379c12f9cc","body_hash":"blake3-16:f9cf83781959814ebc4fb431277ff7bf","participants":["sym:cargo visioncraft . process/linux_proc/"],"calls":[{"target":"sym:cargo visioncraft . process/linux_proc/ids().","confidence":"exact","line":364},{"target":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","confidence":"exact","line":365,"expands":"sym:cargo visioncraft . process/linux_proc/no_longer_member()."},{"target":"sym:cargo visioncraft . process/linux_proc/bounded_read().","confidence":"exact","line":369},{"target":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","confidence":"exact","line":372,"expands":"sym:cargo visioncraft . process/linux_proc/no_longer_member()."},{"target":"sym:cargo visioncraft . process/linux_proc/state().","confidence":"exact","line":378},{"target":"sym:cargo visioncraft . process/linux_proc/dead().","confidence":"exact","line":378},{"target":"sym:cargo visioncraft . process/linux_proc/tasks_dead().","confidence":"exact","line":383,"expands":"sym:cargo visioncraft . process/linux_proc/tasks_dead()."},{"target":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","confidence":"exact","line":387,"expands":"sym:cargo visioncraft . process/linux_proc/no_longer_member()."}],"hash":"blake3:ee87f97968bf4f63ce23188e9b3e96ed180abb5ab2ad8c9f08b5b91944593512"},{"id":"sym:cargo visioncraft . process/linux_proc/group_running().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/linux_proc/group_running().","span":{"start_line":398,"start_col":5,"end_line":430,"end_col":6},"sig_hash":"blake3-16:99a2a0a6fb625ac643156e3927572fa6","body_hash":"blake3-16:66cd29c67e27972c551df4e13580259c","participants":["sym:cargo visioncraft . process/linux_proc/","sym:extern nix","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:cargo visioncraft . process/linux_proc/bounded_read().","confidence":"exact","line":399},{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":400},{"target":"sym:cargo visioncraft . process/linux_proc/unrestricted().","confidence":"exact","line":400},{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":401},{"target":"sym:cargo visioncraft . process/linux_proc/bounded_read().","confidence":"exact","line":405},{"target":"sym:cargo visioncraft . process/linux_proc/state().","confidence":"exact","line":404},{"target":"sym:cargo visioncraft . process/linux_proc/dead_members().","confidence":"exact","line":411,"expands":"sym:cargo visioncraft . process/linux_proc/dead_members()."},{"target":"sym:extern nix::unistd::Pid::from_raw","confidence":"external","line":415},{"target":"sym:extern nix::sys::signal::killpg","confidence":"external","line":415},{"target":"sym:cargo visioncraft . process/group_probe().","confidence":"exact","line":415},{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":417},{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":429}],"hash":"blake3:6f2204d56010527ea7f44aa5c8de7f0dc91868d5e56ecdf52bf420dae22da166"},{"id":"sym:cargo visioncraft . process/run_command_with_env().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/run_command_with_env().","span":{"start_line":518,"start_col":1,"end_line":727,"end_col":2},"sig_hash":"blake3-16:60939e55bba0ee305de92ce58430f493","body_hash":"blake3-16:dcb60b2486836c8f6dd48dcb488714b5","participants":["sym:cargo visioncraft . process/","sym:cargo visioncraft . plan/Invocation#"],"calls":[{"target":"sym:cargo visioncraft . plan/Invocation#validate().","confidence":"exact","line":545,"expands":"sym:cargo visioncraft . plan/Invocation#validate()."},{"target":"sym:cargo visioncraft . process/unix_now().","confidence":"exact","line":548},{"target":"sym:cargo visioncraft . process/private_file().","confidence":"exact","line":552},{"target":"sym:cargo visioncraft . process/private_file().","confidence":"exact","line":553},{"target":"sym:cargo visioncraft . process/unix_now().","confidence":"exact","line":605},{"target":"sym:cargo visioncraft . process/capture().","confidence":"exact","line":614},{"target":"sym:cargo visioncraft . process/capture().","confidence":"exact","line":622},{"target":"sym:cargo visioncraft . process/group_running().","confidence":"exact","line":655,"expands":"sym:cargo visioncraft . process/group_running()."},{"target":"sym:cargo visioncraft . process/signal_group().","confidence":"exact","line":686},{"target":"sym:cargo visioncraft . process/signal_group().","confidence":"exact","line":697},{"target":"sym:cargo visioncraft . process/unix_now().","confidence":"exact","line":723}],"hash":"blake3:27cdad6db51d3eabed0bdbdb4621a85aecb304f5ed2208335c67482e09f1168f"}]}]} diff --git a/docs/diagrams/generated/_overview.md b/docs/diagrams/generated/_overview.md index 53a3429..3b93de0 100644 --- a/docs/diagrams/generated/_overview.md +++ b/docs/diagrams/generated/_overview.md @@ -4,14 +4,18 @@ kind: overview codebase: visioncraft --- # visioncraft overview -9 files · 151 symbols · 572 relations · 69 flows · 492 calls +10 files · 168 symbols · 632 relations · 80 flows · 543 calls ## crates ```mermaid flowchart LR visioncraft(["visioncraft"]) visioncraft_main(["visioncraft_main"]) + Instant{{"Instant"}} + Path{{"Path"}} clap{{"clap"}} + fs{{"fs"}} + io{{"io"}} nix{{"nix"}} recorded{{"recorded"}} sealmap_corpus{{"sealmap_corpus"}} @@ -21,12 +25,16 @@ flowchart LR signal_hook{{"signal_hook"}} tempfile{{"tempfile"}} url{{"url"}} + visioncraft -->|"4"| Instant + visioncraft -->|"3"| Path visioncraft -->|"5"| clap - visioncraft -->|"17"| nix + visioncraft -->|"1"| fs + visioncraft -->|"11"| io + visioncraft -->|"24"| nix visioncraft -->|"5"| recorded visioncraft -->|"37"| sealmap_corpus visioncraft -->|"14"| serde - visioncraft -->|"19"| serde_json + visioncraft -->|"20"| serde_json visioncraft -->|"3"| sha2 visioncraft -->|"7"| tempfile visioncraft -->|"1"| url @@ -44,6 +52,7 @@ flowchart LR visioncraft__deepsec_evidence["deepsec_evidence"] visioncraft__evaluate["evaluate"] visioncraft__evidence["evidence"] + visioncraft__git_metadata["git_metadata"] visioncraft__plan["plan"] visioncraft__process["process"] visioncraft -->|"7"| visioncraft__evaluate @@ -53,9 +62,11 @@ flowchart LR visioncraft__cli -->|"2"| visioncraft__deepsec visioncraft__cli -->|"3"| visioncraft__evaluate visioncraft__cli -->|"16"| visioncraft__evidence + visioncraft__cli -->|"2"| visioncraft__git_metadata visioncraft__cli -->|"13"| visioncraft__plan visioncraft__cli -->|"8"| visioncraft__process visioncraft__deepsec -->|"3"| visioncraft + visioncraft__deepsec -->|"2"| visioncraft__git_metadata visioncraft__deepsec -->|"1"| visioncraft__plan visioncraft__deepsec -->|"8"| visioncraft__process visioncraft__deepsec_evidence -->|"4"| visioncraft diff --git a/docs/diagrams/generated/src/cli.rs.md b/docs/diagrams/generated/src/cli.rs.md index 6fe225c..dec23f9 100644 --- a/docs/diagrams/generated/src/cli.rs.md +++ b/docs/diagrams/generated/src/cli.rs.md @@ -3,8 +3,8 @@ sealmap: 2 source: src/cli.rs module: "sym:cargo visioncraft . cli/" language: rust -source_hash: blake3:e883c6b79fba490bdf06476058ca4078ae6ce7a147e4308b65afd6c1326bdb7d -lines: 1130 +source_hash: blake3:e5a287dcb11e681724fa694daeace991975ed75a6cc4cf342d3328a778ce0c6d +lines: 1135 fragments: 17 --- # `sym:cargo visioncraft . cli/` · src/cli.rs @@ -36,7 +36,7 @@ classDiagram ``` ## `sym:cargo visioncraft . cli/confined().` -`fn confined(root: &Path, relative: &str, directory: bool) -> Result` · L218-L244 +`fn confined(root: &Path, relative: &str, directory: bool) -> Result` · L225-L251 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -66,7 +66,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/read_explicit().` -`fn read_explicit(path: &Path, limit: u64) -> Result<(PathBuf, Vec), CliError>` · L266-L278 +`fn read_explicit(path: &Path, limit: u64) -> Result<(PathBuf, Vec), CliError>` · L273-L285 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -79,7 +79,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/output_path().` -`fn output_path(path: &Path) -> Result` · L280-L305 +`fn output_path(path: &Path) -> Result` · L287-L312 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -105,7 +105,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/write_new().` -`fn write_new(path: &Path, bytes: &[u8]) -> Result<(), CliError>` · L307-L319 +`fn write_new(path: &Path, bytes: &[u8]) -> Result<(), CliError>` · L314-L326 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -121,19 +121,22 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/git().` -`fn git(root: &Path, args: &[&str], cancelled: &AtomicBool) -> Result` · L338-L418 +`fn git(root: &Path, args: &[&str], cancelled: &AtomicBool) -> Result` · L345-L405 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod participant _tempfile as tempfile ext + participant visioncraft__git_metadata as git_metadata mod participant visioncraft__process as process mod visioncraft__cli->>_tempfile: Builder::new() visioncraft__cli->>_tempfile: Builder::prefix(#quot;visioncraft-…) visioncraft__cli->>_tempfile: Builder::permissions(from_mode()) visioncraft__cli->>_tempfile: Builder::tempdir() + visioncraft__cli->>visioncraft__git_metadata: git_metadata::prefix() opt via ok_or_else visioncraft__cli->>visioncraft__cli: error(78, #quot;source root …) end + visioncraft__cli->>visioncraft__git_metadata: git_metadata::fixed_environment() visioncraft__cli->>visioncraft__process: process::run_command_with_env(&invocation, root, path()… alt Termination::Completed if captured.exit_code.is_some() visioncraft__cli->>visioncraft__cli: read_bounded(&captured.stdout, limit)? @@ -149,7 +152,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/revision().` -`fn revision(root: &Path, cancelled: &AtomicBool) -> Result` · L420-L430 +`fn revision(root: &Path, cancelled: &AtomicBool) -> Result` · L407-L417 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -166,7 +169,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/selected_dirty().` -`fn selected_dirty(root: &Path, paths: &[String], cancelled: &AtomicBool) -> Result` · L432-L497 +`fn selected_dirty(root: &Path, paths: &[String], cancelled: &AtomicBool) -> Result` · L419-L484 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -233,7 +236,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/inputs().` -`fn inputs(root: &Path, paths: &[String], missing_ok: bool) -> Result, CliError>` · L506-L534 +`fn inputs(root: &Path, paths: &[String], missing_ok: bool) -> Result, CliError>` · L493-L521 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -260,7 +263,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/source_snapshot().` -`fn source_snapshot(root: &Path, paths: &[String], revision: &str, expected: &[Artifact],) -> Result, CliError>` · L536-L570 +`fn source_snapshot(root: &Path, paths: &[String], revision: &str, expected: &[Artifact],) -> Result, CliError>` · L523-L557 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -284,7 +287,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/init().` -`fn init(options: InitOptions, cancelled: &AtomicBool) -> Result` · L577-L665 +`fn init(options: InitOptions, cancelled: &AtomicBool) -> Result` · L564-L652 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -337,7 +340,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/add_artifact().` -`fn add_artifact(verified: &mut VerifiedArtifacts, root: &Path, artifact: &Artifact,) -> Result<(), CliError>` · L667-L675 +`fn add_artifact(verified: &mut VerifiedArtifacts, root: &Path, artifact: &Artifact,) -> Result<(), CliError>` · L654-L662 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -350,7 +353,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/evidence_parent().` -`fn evidence_parent(root: &Path, path: &str) -> Result` · L687-L698 +`fn evidence_parent(root: &Path, path: &str) -> Result` · L674-L685 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -361,16 +364,14 @@ sequenceDiagram visioncraft__cli->>visioncraft__cli: error(2, #quot;artifact out…) Note over visioncraft__cli: return Err(error(2, #quot;artifact output path is not confin… end - opt let Some(parent) = path.parent() - opt !parent.exists() - visioncraft__cli->>visioncraft__process: process::private_directory(parent) - end + opt let Some(parent) = path.parent() && !parent.exists() + visioncraft__cli->>visioncraft__process: process::private_directory(parent) end visioncraft__cli->>visioncraft__cli: output_path(&path) ``` ## `sym:cargo visioncraft . cli/run().` -`fn run(options: RunOptions, cancelled: &AtomicBool) -> Result` · L772-L928 +`fn run(options: RunOptions, cancelled: &AtomicBool) -> Result` · L759-L915 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -452,7 +453,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/load_receipts().` -`fn load_receipts(directory: &Path, verified: &mut VerifiedArtifacts,) -> Result, CliError>` · L930-L960 +`fn load_receipts(directory: &Path, verified: &mut VerifiedArtifacts,) -> Result, CliError>` · L917-L947 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -478,7 +479,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/evaluate_options().` -`fn evaluate_options(options: EvaluateOptions, cancelled: &AtomicBool) -> Result` · L962-L1089 +`fn evaluate_options(options: EvaluateOptions, cancelled: &AtomicBool) -> Result` · L949-L1094 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -489,6 +490,7 @@ sequenceDiagram participant visioncraft__evaluate___tEvaluationContext as EvaluationContext participant _sealmap_corpus as sealmap_corpus ext participant visioncraft__evaluate as evaluate mod + participant _serde_json as serde_json ext visioncraft__cli->>visioncraft__cli: root(&options.root)? visioncraft__cli->>visioncraft__cli: read_plan(&options.plan)? visioncraft__cli->>visioncraft__cli: revision(&source_root, cancelled)? @@ -506,7 +508,7 @@ sequenceDiagram visioncraft__cli->>visioncraft__cli: read_explicit(path, MAX_JSON)? visioncraft__cli->>visioncraft: crate::from_json(&bytes) visioncraft__cli->>visioncraft__plan___tSubject: validate() - opt supplied.repository != current.repository || supplie… + opt supplied.revision != current.revision || supplied.in… visioncraft__cli->>visioncraft__cli: error(2, #quot;supplied cur…) Note over visioncraft__cli: return Err(error(2, #quot;supplied current subject contradic… end @@ -534,12 +536,13 @@ sequenceDiagram end visioncraft__cli->>visioncraft__evaluate: crate::evaluate(&plan, &receipts, &context) opt options.json - visioncraft__cli->>visioncraft__cli: print_json(&report)? + visioncraft__cli->>_serde_json: serde_json::to_value(&report) + visioncraft__cli->>visioncraft__cli: print_json(&output)? end ``` ## `sym:cargo visioncraft . cli/execute().` -`pub fn execute(cli: Cli, cancelled: &AtomicBool) -> Result` · L1091-L1130 +`pub fn execute(cli: Cli, cancelled: &AtomicBool) -> Result` · L1096-L1135 > Dispatch an explicit CLI operation. ```mermaid sequenceDiagram diff --git a/docs/diagrams/generated/src/deepsec.rs.md b/docs/diagrams/generated/src/deepsec.rs.md index 40a480e..f1840ae 100644 --- a/docs/diagrams/generated/src/deepsec.rs.md +++ b/docs/diagrams/generated/src/deepsec.rs.md @@ -3,8 +3,8 @@ sealmap: 2 source: src/deepsec.rs module: "sym:cargo visioncraft . deepsec/" language: rust -source_hash: blake3:fe5f7e3e8985a7eeb253589267c66d64771af816b56d031e6022a81c9b5649ae -lines: 1013 +source_hash: blake3:f6a856414c586500e5bbcb69b8f4cee3caf40b2de0b8895792ad0ca34e45c977 +lines: 1063 fragments: 5 --- # `sym:cargo visioncraft . deepsec/` · src/deepsec.rs @@ -173,24 +173,30 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . deepsec/Attempt#command().` -`fn command(&mut self, stage: &str, program: &str, args: Vec, cwd: &Path, model: bool, stdin: bool,) -> Result<(i32, Vec), GateError>` · L484-L548 +`fn command(&mut self, stage: &str, program: &str, args: Vec, cwd: &Path, model: bool, stdin: bool,) -> Result<(i32, Vec), GateError>` · L484-L559 ```mermaid sequenceDiagram participant visioncraft__deepsec___tAttempt as Attempt participant visioncraft__deepsec as deepsec mod participant visioncraft__process as process mod + participant visioncraft__git_metadata as git_metadata mod participant _serde_json as serde_json ext opt via ok_or_else visioncraft__deepsec___tAttempt->>visioncraft__deepsec: error(124, #quot;whole-attemp…) end visioncraft__deepsec___tAttempt->>visioncraft__process: private_directory(&directory) - visioncraft__deepsec___tAttempt->>visioncraft__deepsec: environment(self.policy, model) + alt program == #quot;git#quot; + visioncraft__deepsec___tAttempt->>visioncraft__git_metadata: git_metadata::prefix() + visioncraft__deepsec___tAttempt->>visioncraft__git_metadata: git_metadata::fixed_environment() + else + visioncraft__deepsec___tAttempt->>visioncraft__deepsec: environment(self.policy, model) + end visioncraft__deepsec___tAttempt->>_serde_json: serde_json::to_vec_pretty(&invocation) opt via map_err visioncraft__deepsec___tAttempt->>visioncraft__deepsec: error(70, #quot;invocation s…) end visioncraft__deepsec___tAttempt->>visioncraft__deepsec: write_new(&join(), &_)? - visioncraft__deepsec___tAttempt->>visioncraft__process: run_command(&invocation, cwd, &directory, self.cancelle… + visioncraft__deepsec___tAttempt->>visioncraft__process: run_command_with_env(&invocation, cwd, &directory, self… visioncraft__deepsec___tAttempt->>visioncraft__deepsec: read_bounded(&run.stdout, self.policy.max_output_bytes)? visioncraft__deepsec___tAttempt->>visioncraft__deepsec: read_bounded(&run.stderr, self.policy.max_output_bytes)? visioncraft__deepsec___tAttempt->>_serde_json: serde_json::to_vec_pretty(&execution) @@ -214,7 +220,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . deepsec/execute().` -`pub fn execute(options: &DeepsecOptions, cancelled: &AtomicBool) -> Result` · L571-L975 +`pub fn execute(options: &DeepsecOptions, cancelled: &AtomicBool) -> Result` · L618-L1025 > Execute an explicitly requested security gate, returning its legacy exit code. ```mermaid sequenceDiagram @@ -274,6 +280,7 @@ sequenceDiagram Note over visioncraft__deepsec: return Err(error(70, #quot;review workspace unavailable#quot;)) end visioncraft__deepsec->>visioncraft__deepsec: workspace_lock(&workspace)? + visioncraft__deepsec->>visioncraft__deepsec: validate_workspace_tree(&workspace)? opt fs::symlink_metadata(&report).is_ok() visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;report direc…) Note over visioncraft__deepsec: return Err(error(78, #quot;report directory must be new#quot;)) @@ -285,8 +292,9 @@ sequenceDiagram visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;plan seriali…) end visioncraft__deepsec->>visioncraft__deepsec: write_new(&join(), &_)? - opt !workspace.join(#quot;.gitignore#quot;).exists() - visioncraft__deepsec->>visioncraft__deepsec: write_new(&join(), b#quot;*\n#quot;)? + visioncraft__deepsec->>_tempfile: NamedTempFile::new_in(&workspace) + opt via map_err + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;cannot final…) end opt fs::symlink_metadata(&config).is_ok_and(| m |!m.is_f… visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;configuratio…) diff --git a/docs/diagrams/generated/src/deepsec_evidence.rs.md b/docs/diagrams/generated/src/deepsec_evidence.rs.md index 429d9d5..54c4288 100644 --- a/docs/diagrams/generated/src/deepsec_evidence.rs.md +++ b/docs/diagrams/generated/src/deepsec_evidence.rs.md @@ -3,7 +3,7 @@ sealmap: 2 source: src/deepsec_evidence.rs module: "sym:cargo visioncraft . deepsec_evidence/" language: rust -source_hash: blake3:7bdca6b97bbbee14a261123c7f4f1a363cf86abefbaf059141d6e3f8985a36d2 +source_hash: blake3:f26a627cb792b2b78f7637d38ad80a0e0260b566505bedf92cd524d64dd5a0ac lines: 317 fragments: 6 --- diff --git a/docs/diagrams/generated/src/evaluate.rs.md b/docs/diagrams/generated/src/evaluate.rs.md index acddb6f..e13a8ca 100644 --- a/docs/diagrams/generated/src/evaluate.rs.md +++ b/docs/diagrams/generated/src/evaluate.rs.md @@ -3,8 +3,8 @@ sealmap: 2 source: src/evaluate.rs module: "sym:cargo visioncraft . evaluate/" language: rust -source_hash: blake3:e2b3c4721974ba40222309382bfb4dc2a311296e18b7324982cd29215db905a1 -lines: 658 +source_hash: blake3:68c30067ced8712ddcf6cb6c32ff742f62c952f39d3d4fa57951fe599b7da94c +lines: 657 fragments: 4 --- # `sym:cargo visioncraft . evaluate/` · src/evaluate.rs @@ -149,10 +149,8 @@ sequenceDiagram opt output_bytes> check.invocation.max_output_bytes Note over visioncraft__evaluate: return error(#quot;verified raw output exceeds configured ca… end - opt let Some(snapshot) = &receipt.subject.working_tree - opt !context.verified.contains(snapshot) - Note over visioncraft__evaluate: return error(#quot;dirty working-tree snapshot has not been … - end + opt let Some(snapshot) = &receipt.subject.working_tree &… + Note over visioncraft__evaluate: return error(#quot;dirty working-tree snapshot has not been … end alt Some(paths) if !check.scope.iter().all(| p | paths.cont… Note over visioncraft__evaluate: return (CheckOutcome::Inconclusive, vec![#quot;observed scop… diff --git a/docs/diagrams/generated/src/git_metadata.rs.md b/docs/diagrams/generated/src/git_metadata.rs.md new file mode 100644 index 0000000..8d62f15 --- /dev/null +++ b/docs/diagrams/generated/src/git_metadata.rs.md @@ -0,0 +1,22 @@ +--- +sealmap: 2 +source: src/git_metadata.rs +module: "sym:cargo visioncraft . git_metadata/" +language: rust +source_hash: blake3:36f06c2d0b9d416dc106fd7d20839a5fc424fa52dc1e40f572a1acb24050a467 +lines: 30 +fragments: 1 +--- +# `sym:cargo visioncraft . git_metadata/` · src/git_metadata.rs +> Shared policy for read-only Git metadata inspection, not user build commands. + +## structure +```mermaid +classDiagram + direction LR + class visioncraft__git_metadata["visioncraft::git_metadata"] { + <> + ~fixed_environment(crate) BTreeMap#lt;String, String#gt; + ~prefix(crate) Vec#lt;String#gt; + } +``` diff --git a/docs/diagrams/generated/src/lib.rs.md b/docs/diagrams/generated/src/lib.rs.md index 18511d1..625000a 100644 --- a/docs/diagrams/generated/src/lib.rs.md +++ b/docs/diagrams/generated/src/lib.rs.md @@ -3,8 +3,8 @@ sealmap: 2 source: src/lib.rs module: "sym:cargo visioncraft ." language: rust -source_hash: blake3:337326f4db730b3c5a5b0457e94f425a596bc8dd6d765e3e51bc9d78bc56b9ad -lines: 129 +source_hash: blake3:bd0cbb39c4723d919330852c9a157a2284d5b8102817d2c74eb7dd89a715bffb +lines: 132 fragments: 1 --- # `sym:cargo visioncraft .` · src/lib.rs @@ -28,6 +28,7 @@ classDiagram +mod evaluate +mod evidence +from_json(bytes: &[u8]) Result#lt;T, ContractError#gt; + +mod git_metadata ~hex(crate) bool ~identifier(crate) bool ~nonempty(crate) bool diff --git a/docs/diagrams/generated/src/main.rs.md b/docs/diagrams/generated/src/main.rs.md index 9c33e65..d65f670 100644 --- a/docs/diagrams/generated/src/main.rs.md +++ b/docs/diagrams/generated/src/main.rs.md @@ -3,8 +3,8 @@ sealmap: 2 source: src/main.rs module: "sym:cargo visioncraft_main ." language: rust -source_hash: blake3:99d2860c356b50b40860a89032581ec5c2ae5c16e89fca73d9a59be073f78872 -lines: 38 +source_hash: blake3:4bb59bf863aec89c7e0f6ea0dc232c477e58b0d54775b003a29d43b892e22326 +lines: 39 fragments: 1 --- # `sym:cargo visioncraft_main .` · src/main.rs diff --git a/docs/diagrams/generated/src/process.rs.md b/docs/diagrams/generated/src/process.rs.md index ba628ce..9836e32 100644 --- a/docs/diagrams/generated/src/process.rs.md +++ b/docs/diagrams/generated/src/process.rs.md @@ -3,9 +3,9 @@ sealmap: 2 source: src/process.rs module: "sym:cargo visioncraft . process/" language: rust -source_hash: blake3:b24b8fb96eba5f197c4a00e8da464df9d6d53b98c4db058f9b684e8da1c64e3c -lines: 425 -fragments: 2 +source_hash: blake3:aba99dafa4cb40a2a286eaa16908067cf850cba5953360fec3b16569bfff0d28 +lines: 727 +fragments: 7 --- # `sym:cargo visioncraft . process/` · src/process.rs > Bounded local command execution. @@ -50,13 +50,139 @@ classDiagram visioncraft__process___tCapturedRun *-- visioncraft__process___tTermination : termination ``` +## `sym:cargo visioncraft . process/group_running().` +`fn group_running(pid: u32, deadline: Instant) -> io::Result` · L205-L227 +```mermaid +sequenceDiagram + participant visioncraft__process as process mod + participant _nix as nix ext + participant visioncraft__process__linux_proc as linux_proc mod + visioncraft__process->>_nix: Pid::from_raw(group) + visioncraft__process->>_nix: signal::killpg(from_raw(), None) + visioncraft__process->>visioncraft__process: group_probe(killpg())? + opt !group_probe(killpg(Pid::from_raw(group), None))? + Note over visioncraft__process: return Ok(false) + end + visioncraft__process->>visioncraft__process__linux_proc: linux_proc::group_running(group, deadline) +``` + +## `sym:cargo visioncraft . process/linux_proc/no_longer_member().` +`fn no_longer_member(pid: u32, group: i32) -> io::Result` · L330-L338 +```mermaid +sequenceDiagram + participant visioncraft__process__linux_proc as linux_proc mod + participant _nix as nix ext + participant _io as io ext + opt via map_err + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: unknown() + end + visioncraft__process__linux_proc->>_nix: Pid::from_raw(_) + visioncraft__process__linux_proc->>_nix: unistd::getpgid(Some()) + opt Err(error) + visioncraft__process__linux_proc->>_io: Error::from(error) + end +``` + +## `sym:cargo visioncraft . process/linux_proc/tasks_dead().` +`fn tasks_dead(process: &Path, group: i32, deadline: Instant) -> io::Result` · L340-L360 +```mermaid +sequenceDiagram + participant visioncraft__process__linux_proc as linux_proc mod + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: ids(&join(), deadline)? + opt tasks.is_empty() + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: unknown() + Note over visioncraft__process__linux_proc: return Err(unknown()) + end + loop for tid in tasks + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: bounded_read(&join(), 8192) + alt Err(error) if error.kind() == io::ErrorKind::NotFound &… + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: no_longer_member(tid, group)? + else Err(error) + Note over visioncraft__process__linux_proc: return Err(error) + end + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: state(&record, tid, Some())? + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: dead(_) + opt !dead(state(&record, tid, Some(group))?) + Note over visioncraft__process__linux_proc: return Ok(false) + end + end +``` + +## `sym:cargo visioncraft . process/linux_proc/dead_members().` +`fn dead_members(group: i32, deadline: Instant) -> io::Result>>` · L362-L396 +```mermaid +sequenceDiagram + participant visioncraft__process__linux_proc as linux_proc mod + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: ids(new(), deadline)? + loop for pid in ids(Path::new(#quot;/proc#quot;), deadline)? + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: no_longer_member(pid, group)? + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: bounded_read(&join(), 8192) + alt Err(error) if error.kind() == io::ErrorKind::NotFound &… + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: no_longer_member(pid, group)? + else Err(error) + Note over visioncraft__process__linux_proc: return Err(error) + end + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: state(&record, pid, Some())? + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: dead(_) + opt !dead(state(&record, pid, Some(group))?) + Note over visioncraft__process__linux_proc: return Ok(None) + end + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: tasks_dead(&process, group, deadline) + alt Ok(false) + Note over visioncraft__process__linux_proc: return Ok(None) + else Err(error) if error.kind() == io::ErrorKind::NotFound &… + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: no_longer_member(pid, group)? + else Err(error) + Note over visioncraft__process__linux_proc: return Err(error) + end + end +``` + +## `sym:cargo visioncraft . process/linux_proc/group_running().` +`pub(super) fn group_running(group: i32, deadline: Instant) -> io::Result` · L398-L430 +```mermaid +sequenceDiagram + participant visioncraft__process__linux_proc as linux_proc mod + participant _nix as nix ext + participant visioncraft__process as process mod + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: bounded_read(new(), 1_048_576)? + opt via map_err + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: unknown() + end + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: unrestricted(_) + opt !unrestricted(std::str::from_utf8(&mounts).map_err(|… + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: unknown() + Note over visioncraft__process__linux_proc: return Err(unknown()) + end + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: bounded_read(new(), 8192)? + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: state(&_, id(), None)? + loop for _ in 0..3 + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: dead_members(group, deadline)? + opt let-else + Note over visioncraft__process__linux_proc: return Ok(true) + end + opt members.is_empty() + visioncraft__process__linux_proc->>_nix: Pid::from_raw(group) + visioncraft__process__linux_proc->>_nix: signal::killpg(from_raw(), None) + visioncraft__process__linux_proc->>visioncraft__process: super::group_probe(killpg())? + opt super::group_probe(nix::sys::signal::killpg(Pid::fro… + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: unknown() + end + Note over visioncraft__process__linux_proc: return if super::group_probe(nix::sys::signal::killpg(P… + end + opt previous.as_ref() == Some(&members) + Note over visioncraft__process__linux_proc: return Ok(false) + end + end + visioncraft__process__linux_proc->>visioncraft__process__linux_proc: unknown() +``` + ## `sym:cargo visioncraft . process/run_command_with_env().` -`pub(crate) fn run_command_with_env(invocation: &Invocation, root: &Path, output: &Path, cancelled: &AtomicBool, inherit_stdin: bool, overrides: &std::collections::BTreeMap,) -> io::Re…` · L225-L425 +`pub(crate) fn run_command_with_env(invocation: &Invocation, root: &Path, output: &Path, cancelled: &AtomicBool, inherit_stdin: bool, overrides: &std::collections::BTreeMap,) -> io::Re…` · L518-L727 ```mermaid sequenceDiagram participant visioncraft__process as process mod participant visioncraft__plan___tInvocation as Invocation - participant _nix as nix ext visioncraft__process->>visioncraft__plan___tInvocation: validate() visioncraft__process->>visioncraft__process: unix_now() visioncraft__process->>visioncraft__process: private_file(&stdout_path)? @@ -74,10 +200,7 @@ sequenceDiagram visioncraft__process->>visioncraft__process: capture(expect(), stdout_file, clone(), clone(), clone(… visioncraft__process->>visioncraft__process: capture(expect(), stderr_file, total, clone(), clone(),… opt result.termination == Termination::Completed - opt via is_ok_and - visioncraft__process->>_nix: Pid::from_raw(p) - visioncraft__process->>_nix: signal::killpg(from_raw(), None) - end + visioncraft__process->>visioncraft__process: group_running(pid, _) end opt result.termination != Termination::Completed visioncraft__process->>visioncraft__process: signal_group(pid, SIGINT) From e3306776ebab083a7842b02ce4fec4e0a2bbc77c Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 3 Nov 2026 12:06:11 +0000 Subject: [PATCH 15/16] Bind assessment freshness and retain safe child identity through cleanup --- README.md | 10 +- docs/REVIEW-2026-11-03.md | 29 ++- docs/UPSTREAM-DEEPSEC.md | 35 ++- docs/ZEROSHOT-LESSONS.md | 10 + .../visioncraft/references/quality-gates.md | 12 + .../visioncraft/references/review-evidence.md | 27 +++ src/cli.rs | 29 +-- src/deepsec.rs | 93 +++++--- src/deepsec_evidence.rs | 214 +++++++++++++++--- src/evaluate.rs | 9 + src/git_metadata.rs | 112 +++++++++ src/process.rs | 198 ++++++++++++---- tests/core.rs | 85 ++++++- tests/deepsec.rs | 182 ++++++++++++++- tests/fixtures/deepsec.py | 5 +- tests/native_cli.rs | 2 +- tests/process.rs | 2 +- 17 files changed, 904 insertions(+), 150 deletions(-) diff --git a/README.md b/README.md index be7a925..9f3936a 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,8 @@ It is not proof of correctness, security, complete test coverage or deployment. ## Install -Rust 1.88 or later is required. The process CLI currently supports Unix. +Rust 1.88 or later is required. Native execution currently supports Linux with glibc or musl; +the deterministic library remains independent of the operating system. ```sh cargo install visioncraft --locked --version 0.1.0 @@ -226,14 +227,15 @@ boundaries. Other hosts can supply their own adapters without importing them. ## Limits and development The process runner is **not a sandbox**. Children retain the caller's filesystem -and network authority; environment filtering is not secret isolation. Unix +and network authority; environment filtering is not secret isolation. Linux process groups support cancellation and deadlines, but a deliberately escaping process or a blocked kernel filesystem call needs host-level containment. Private capture directories protect ordinary local handling, not a hostile concurrent filesystem. Keep source-bearing evidence out of public commits. Linux can recognise exited zombie group members through an unrestricted `/proc` -view; hidden, unreadable or uncertain state remains non-passing. Other Unix -platforms conservatively reject any surviving group, including zombies. +view; hidden, unreadable or uncertain state remains non-passing. Native execution +on other platforms returns unsupported before spawning a child. Process-wide +child reapers must not compete with the runner's ownership of its children. Run `cargo test`, `cargo clippy --all-targets -- -D warnings`, `cargo fmt --check` and `RUSTDOCFLAGS='-D warnings' cargo doc --no-deps`. The diff --git a/docs/REVIEW-2026-11-03.md b/docs/REVIEW-2026-11-03.md index f56d485..5019df3 100644 --- a/docs/REVIEW-2026-11-03.md +++ b/docs/REVIEW-2026-11-03.md @@ -14,7 +14,7 @@ in the host's `visioncraft-20261103/adversarial/attempt-1` evidence archive. | Nested review checkpoint paths can redirect writes | Reproduced with symlinks at data, nested file and ignore paths. Bounded recursive inspection rejects links and special files before invoking the external tool; the ignore file is replaced privately. | | Repository/configuration labels appear automatically freshness-checked | The CLI now distinguishes observed source bytes from opaque caller declarations. Explicit current-subject labels feed the core comparison; changed configuration bytes must be selected inputs for automatic verification. | | Invalid Unicode argument panics on the parser error path | Reproduced as exit 101. The error path now inspects OS strings; malformed arguments retain the documented exit codes. | -| A zombie process group member causes a false capture failure | Reproduced separately from the live-descendant control. Linux checks distinguish proven exited group members from live or unknown state; other Unix platforms remain conservative. | +| A zombie process group member causes a false capture failure | Reproduced separately from the live-descendant control. Linux checks distinguish proven exited group members from live or unknown state; unsupported native execution targets are rejected before spawning. | The first Agentbox review also identified private JSON-write and placeholder expansion defects. Their reproductions, repairs and trust-boundary disposition @@ -26,3 +26,30 @@ The first fresh CI run separately caught a rustdoc link and a Rust 1.85 claim that a transitive dependency could not satisfy. The link was corrected and the declared minimum raised to Rust 1.88, with an explicit CI job. Test success and review completion remain separate release evidence. + +## Second review and scope limits + +The second investigation covered eleven selected files at +`2c5a625ce245be2a5ec2f0b30633d708b50afb9e` and returned nine further findings. +Its processing completed, but its gate remains `ERROR`: reviewers disclosed +omitted neighbouring context. Separate reviewers reading each file does not +establish that every caller/callee interaction was investigated. The strict +scope policy was retained. Missing or malformed `refusal.skipped` metadata is +also rejected, with explicit negative controls. + +| Finding | Disposition and control | +| --- | --- | +| Clean filters can run through Git status/working diff; shared prefix is insufficient | Reproduced with a marker-writing clean filter. Metadata now compares tree/index IDs and raw `hash-object --no-filters` results; the native CLI shares the tree parser. No status or working-diff invocation is used. | +| Ordinary preseeded state can be tracked or contain loader inputs | Tracked review state and unmanaged workspace-root entries are refused before the reviewer runs. Known configuration/ignore files are written privately; current-run and exact-byte requirements still apply to checkpoint records. | +| Historical reports consume the active-state traversal budget | Historical report contents are not revisited as reviewer inputs. Fresh output paths remain validated; active checkpoint data retains an explicit bound and documented external archival procedure. | +| Full scans refuse symlinks, submodules or oversized files | Deliberate supported-input boundary. No files are silently omitted from a claimed complete scope. Use an explicit narrower file manifest and record exclusions. | +| Manual/audit expectation status can remain passed against stale current context | Reproduced independently of the aggregate gate. Assessments now apply current subject/ancestry/input/configuration checks; changed-context and unchanged/known-ancestor controls cover both outcomes. | +| Elapsed duration differs from wall-clock timestamp span | These are independent clock domains: `Instant` enforces deadlines, while wall timestamps identify observations. Equality would reject valid runs after clock adjustment and would not authenticate imported receipts. The distinction and deadline control are explicit. | +| Legitimate symlinked output ancestors are rejected | Deliberate output-path contract. Canonicalise an explicitly trusted root before invocation; the runner does not silently follow arbitrary output links. | +| Reaping the process leader before delayed group signalling allows PID reuse | The runner now observes Linux exits with safe `waitid(WNOWAIT)` while retaining the leader through final signalling, then reaps. A lost-child-ownership control verifies that no further group signal is sent. Unsupported execution platforms are refused before spawning. | + +Local/CI checks and a real protocol smoke review are separate from these broad +production investigations. A smoke test can qualify the adapter's completion +path; it cannot turn either retained production `ERROR` receipt into `PASS` or +establish complete security coverage. Host baseline issues remain in the host's +review record, with actual comparison evidence rather than an inferred label. diff --git a/docs/UPSTREAM-DEEPSEC.md b/docs/UPSTREAM-DEEPSEC.md index 7907d14..25b75b0 100644 --- a/docs/UPSTREAM-DEEPSEC.md +++ b/docs/UPSTREAM-DEEPSEC.md @@ -47,12 +47,21 @@ differ is refused; use an exact index checkout. Full mode scans first, then processes the selected pending candidates. No pending candidates means no new review, not a clean full review. Scan-only output cannot satisfy model review. +Metadata requires a Git checkout with a resolvable `HEAD`. `dirty_scope` is +`selected-inputs`: the dirty flag compares only selected raw bytes with their +committed blobs, not every file in the repository. Raw object hashing bypasses +Git attribute conversions. A normal LFS configuration or an unselected large +asset therefore does not prevent an explicit small-file review. Whole-tree or +reference-diff selection can still require a narrower manifest when expanded +assets exceed the supported file bound. + Completion requires one fresh persisted processing run for the expected project and root, phase `done`, a completion timestamp, and a processed-file count equal to the selected review set. Every selected file must have an `analyzed` record with the expected path, project and content hash, plus exactly one history entry for that run. That entry must name the model and agent, report positive output -tokens, state `refusal.refused: false`, and contain no skipped scope. Missing, +tokens, state `refusal.refused: false`, and carry an explicitly empty +`refusal.skipped` array. Missing, malformed, zero-work, refused, partial or contradictory records prevent a pass. Retain the run and file records, raw export, normalised findings and all bounded @@ -105,8 +114,13 @@ approval. A name prefix would not establish that trust or authorise a recipient. Metadata probes share the native CLI's restricted Git environment and disable repository filesystem-monitor hooks. Review checkpoints reject symlinks, hard -links and special files throughout the bounded state tree before invoking -Deepsec, and rewrite their ignore file privately. Existing ordinary checkpoint +links and special files in active state before invoking Deepsec, reject tracked +state and unexpected loader inputs at the workspace root, and rewrite their +ignore file privately. Historical reports are not active reviewer inputs and +are not recursively revisited. Each new report still requires a fresh path and +ordinary parent directories. Active data retains a 100,000-entry / 64-level +ceiling: archive old checkpoint data externally if that bound is reached; no +user evidence is silently deleted. Existing ordinary checkpoint records are not proof of a fresh review: current run identity and exact source hashes remain required. These checks do not isolate concurrent writers with the same Unix identity or the reviewer's own tools. @@ -118,3 +132,18 @@ the host. Source-bearing output stays in private evidence locations according to that host's policy. See the portable [operating method](../skills/visioncraft/references/deepsec.md) and [Agentbox example](../skills/visioncraft/references/ecosystem-agentbox.md). + +## Conservative scope handling + +A nonempty skipped-context list keeps the gate non-passing, even when another +batch separately read a neighbouring file. Separate file presence does not prove +that a caller/callee security boundary was investigated. Preserve the original +ERROR receipt and recorded limitations. A future explicit coverage policy would +need to distinguish exact selected-file coverage from contextual assurance; the +current adapter does not silently make that change. An empty list is a recorded +claim, not proof of complete semantic understanding. + +Full/scan modes require ordinary confined files within the documented per-file +and aggregate bounds. Symlinks, submodules and oversized inputs are refused, +rather than silently omitted from a supposedly complete review. An explicit +file manifest can select a narrower scope; record its exclusions separately. diff --git a/docs/ZEROSHOT-LESSONS.md b/docs/ZEROSHOT-LESSONS.md index ca031e6..b82e743 100644 --- a/docs/ZEROSHOT-LESSONS.md +++ b/docs/ZEROSHOT-LESSONS.md @@ -21,6 +21,10 @@ ceiling, beside an exact-boundary passing control. This bounds one declared pass, not arbitrary repeated invocations or blocked kernel I/O. VisionCraft has no retry graph or implicit model worker fleet. +The canonical [quality-gate method](../skills/visioncraft/references/quality-gates.md) +also requires aggregate admission before workers start and leaves retry/spend +limits with the host. + ## Review sessions and authority Zeroshot's software-change workflow retains the worker session for repairs and @@ -64,6 +68,12 @@ writer quiescence and credential refresh. The foreground VisionCraft CLI owns its child process group and cancels it on interruption; it is not a detached controller. Host adapters must state which lifetime they control. +The [review-evidence method](../skills/visioncraft/references/review-evidence.md#resume-from-an-explicit-checkpoint) +now specifies predecessor attempt/checkpoint links, fresh captures, credential +resolution, writer quiescence and checking an unknown external effect before +retry. This is host workflow guidance; it does not claim the crate automatically +records recovery lineage or runs a recovery service. + ## Optional future consumption Zeroshot publishes separate protocol, server, client and testkit crates in its diff --git a/skills/visioncraft/references/quality-gates.md b/skills/visioncraft/references/quality-gates.md index 85b41a3..5963607 100644 --- a/skills/visioncraft/references/quality-gates.md +++ b/skills/visioncraft/references/quality-gates.md @@ -33,6 +33,13 @@ it does not pre-populate successful evidence. ## Workflow through the gates +Before starting checks, validate the complete plan and its aggregate resource +budget, including optional checks. Per-check deadlines do not bound an unlimited +sequence or a host's retry loop. VisionCraft admits at most 1,024 checks, one day +of summed declared deadlines and one GiB of summed capture limits per plan. +The host must separately bound retries, model spend and concurrent runs. An +invalid plan must not start a worker; a missing evaluator remains unavailable. + Clarify intent and domain boundaries, record the expectations that matter, implement with a testable feedback loop, produce evidence, perform applicable review and challenge, stabilise important scenarios, then assess release and @@ -45,6 +52,11 @@ subject revision and configuration. Paid external review follows the current project's cadence; do not run it automatically after every increment. A check before later edits must not be presented as review of the final diff. +Give a repair reviewer a fresh context containing the current candidate, required +claims, raw evidence and previous finding IDs/dispositions. Keep the implementer's +narrative identifiable as a claim. Session freshness does not establish independent +model families, and a new run ID does not revalidate unchanged cached findings. + When available, [AQE's direct tools](agentic-qe.md) can propose tests and explain coverage gaps. Preserve the generated source and measurement provenance, then run the real project tests and instrumentation. Its static analysis and fixed diff --git a/skills/visioncraft/references/review-evidence.md b/skills/visioncraft/references/review-evidence.md index 2388768..cfda2b2 100644 --- a/skills/visioncraft/references/review-evidence.md +++ b/skills/visioncraft/references/review-evidence.md @@ -135,6 +135,27 @@ check source writes and receipts for truncation before retrying. Restore known reviewed bytes, rerun affected checks, and reclaim only owned caches after preserving evidence. Another worker's build directory is not spare space. +## Resume from an explicit checkpoint + +An interrupted attempt keeps its identity, raw captures and incomplete outcome. +Create a successor with a new attempt ID and fresh output directory. In the +host's existing task or handoff record, link the predecessor attempt and the +exact checkpoint revision, selected-input hashes, configuration identity, +interruption reason and required checks that must run again. Resolve credentials +through the host; do not copy their values into the checkpoint. + +Before resuming, establish which writers and external effects remain active. +Detaching an observer is different from stopping a controller. Quiesce conflicting +writers through the host's existing lifecycle before restoring files, then check +the restored bytes. Do not blindly retry a publish/payment/deploy operation after +an unknown response: observe the destination and use its idempotency contract. + +This lineage is a host workflow requirement, not an automatically populated +VisionCraft receipt field or a new recovery engine. The CLI already requires +fresh execution directories and validates current evidence; the host records +the predecessor relationship. Preserve failed attempts rather than appending a +successful continuation to their captures or retrospectively relabelling them. + ## Close out without changing the claim Keep finding IDs and the raw export hash bound to the same bytes. Evidence of @@ -156,6 +177,12 @@ consumer source/checksum before claiming adoption. Reuse checksum-verified release artefacts where the release contract requires them; do not silently substitute locally compiled bytes for a reviewed toolchain pin. +For delivery, record the actual destination and final writer alongside the +observed release digest/version or running instance identity. A successful +delivery cannot turn a failed quality run into a pass, and a passing quality +run cannot establish delivery. Reuse Sealmap delivery attestations and the +host's receipts rather than introducing another status database. + Naming/discovery repairs do not migrate prior state. Define precedence, conflicts and recovery for records under the old convention. For permission data, verify both retained owner access and denied access after migration. diff --git a/src/cli.rs b/src/cli.rs index d80ef2d..5e4f8ca 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -419,36 +419,19 @@ fn revision(root: &Path, cancelled: &AtomicBool) -> Result { fn selected_dirty(root: &Path, paths: &[String], cancelled: &AtomicBool) -> Result { // Git status/diff may invoke configured clean filters. Compare unfiltered // committed blob bytes instead; worktree conversion differences are dirty. - let mut args = vec!["ls-tree", "-z", "--full-tree", "HEAD", "--"]; - args.extend(paths.iter().map(String::as_str)); + let arguments = crate::git_metadata::tree_arguments("HEAD", paths); + let args: Vec<_> = arguments.iter().map(String::as_str).collect(); let output = git(root, &args, cancelled)?; if !output.success { return Err(error(70, "could not inspect selected Git input status")); } - let mut entries = std::collections::BTreeMap::new(); - for row in output - .stdout - .split(|b| *b == 0) - .filter(|row| !row.is_empty()) - { - let (meta, path) = row.split_at( - row.iter() - .position(|b| *b == b'\t') - .ok_or_else(|| error(70, "invalid Git tree record"))?, - ); - let meta = std::str::from_utf8(meta).map_err(|_| error(70, "invalid Git tree metadata"))?; - let fields: Vec<_> = meta.split_whitespace().collect(); - if fields.len() != 3 || fields[1] != "blob" { - continue; - } - let path = std::str::from_utf8(&path[1..]) - .map_err(|_| error(70, "selected Git path is not UTF-8"))?; - entries.insert(path.to_owned(), fields[2].to_owned()); - } + let entries = + crate::git_metadata::tree_entries(&output.stdout).map_err(|message| error(70, message))?; for path in paths { - let Some(object) = entries.get(path) else { + let Some(entry) = entries.get(path) else { return Ok(true); }; + let object = &entry.object; if !crate::hex(object, &[40, 64]) { return Err(error(70, "invalid Git object identifier")); } diff --git a/src/deepsec.rs b/src/deepsec.rs index 861b2b1..acb646d 100644 --- a/src/deepsec.rs +++ b/src/deepsec.rs @@ -597,6 +597,23 @@ fn validate_workspace_tree(workspace: &Path) -> Result<(), GateError> { return Err(error(78, "review workspace exceeds traversal bounds")); } let entry = entry.map_err(io_error)?; + let name = entry.file_name(); + if depth == 0 + && ![ + "data", + "reports", + "deepsec.config.mjs", + ".gitignore", + ".visioncraft.lock", + ] + .iter() + .any(|allowed| name == std::ffi::OsStr::new(allowed)) + { + return Err(error( + 78, + "review workspace contains unmanaged loader inputs", + )); + } let meta = fs::symlink_metadata(entry.path()).map_err(io_error)?; if meta.file_type().is_symlink() || !(meta.is_dir() || meta.is_file()) @@ -608,6 +625,11 @@ fn validate_workspace_tree(workspace: &Path) -> Result<(), GateError> { )); } if meta.is_dir() { + // Past report contents are never active reviewer state. Fresh + // outputs separately check every parent and refuse existing paths. + if depth == 0 && name == "reports" { + continue; + } pending.push((entry.path(), depth + 1)); } } @@ -634,12 +656,12 @@ pub fn execute(options: &DeepsecOptions, cancelled: &AtomicBool) -> Result from_json::(text.as_bytes()) @@ -775,28 +797,6 @@ pub fn execute(options: &DeepsecOptions, cancelled: &AtomicBool) -> Result Result = None; let mut observed_version: Option = None; let outcome = (|| -> Result { + recorded::refuse_tracked_workspace(&mut attempt, &root)?; + // Preserve repository-controlled bytes on refusal. Only after the + // read-only index probe may managed reviewer files be replaced. + let mut ignore = tempfile::NamedTempFile::new_in(&workspace).map_err(io_error)?; + ignore.write_all(b"*\n").map_err(io_error)?; + ignore + .persist(workspace.join(".gitignore")) + .map_err(|_| error(70, "cannot finalise review ignore file"))?; + let config = workspace.join("deepsec.config.mjs"); + if fs::symlink_metadata(&config) + .is_ok_and(|m| !m.is_file() || m.file_type().is_symlink()) + { + return Err(error(78, "configuration path is not an ordinary file")); + } + let config_value = + json!({"ai":route,"projects":[{"id":project_id,"root":root}],"dataDir":"./data"}); + let config_text = format!( + "// Generated by VisionCraft; credential names only.\nexport default {};\n", + serde_json::to_string_pretty(&config_value) + .map_err(|_| error(70, "configuration serialisation failed"))? + ); + let mut staged = tempfile::NamedTempFile::new_in(&workspace).map_err(io_error)?; + staged.write_all(config_text.as_bytes()).map_err(io_error)?; + staged.as_file().sync_all().map_err(io_error)?; + staged + .persist(&config) + .map_err(|_| error(70, "cannot finalise review configuration"))?; let (rc, version) = attempt.command( "version", "deepsec", @@ -846,18 +873,8 @@ pub fn execute(options: &DeepsecOptions, cancelled: &AtomicBool) -> Result Result Result, G }) .collect() } +fn git_bytes( + attempt: &mut Attempt<'_>, + root: &Path, + stage: &str, + args: Vec, +) -> Result, GateError> { + let (rc, bytes) = attempt.command(stage, "git", args, root, false, false)?; + if rc != 0 { + return Err(error(78, "could not inspect read-only Git metadata")); + } + Ok(bytes) +} + +fn tree( + attempt: &mut Attempt<'_>, + root: &Path, + reference: &str, +) -> Result, GateError> { + if reference.starts_with('-') { + return Err(error(78, "diff reference must not be a Git option")); + } + let bytes = git_bytes( + attempt, + root, + "reference-tree", + crate::git_metadata::tree_arguments(reference, &[]), + )?; + crate::git_metadata::tree_entries(&bytes).map_err(|message| error(78, message)) +} + +fn index( + attempt: &mut Attempt<'_>, + root: &Path, +) -> Result, GateError> { + let bytes = git_bytes( + attempt, + root, + "index-entries", + vec![ + "ls-files".into(), + "--stage".into(), + "-z".into(), + "--".into(), + ], + )?; + crate::git_metadata::index_entries(&bytes).map_err(|message| error(78, message)) +} + +fn working_hashes( + attempt: &mut Attempt<'_>, + root: &Path, + paths: &[String], +) -> Result, GateError> { + if paths.len() > 100_000 { + return Err(error(78, "review file count exceeds 100000")); + } + let mut hashes = BTreeMap::new(); + for chunk in paths.chunks(64) { + let mut present = Vec::new(); + for name in chunk { + if !root + .join(name) + .try_exists() + .map_err(|_| error(70, "source existence is unavailable"))? + { + continue; + } + let path = confined(root, name)?; + let meta = fs::metadata(&path).map_err(|_| error(70, "source metadata unavailable"))?; + if !meta.is_file() || meta.len() > 32 * 1024 * 1024 { + return Err(error( + 78, + "raw review input must be an ordinary file at most 32 MiB", + )); + } + present.push(name.clone()); + } + if present.is_empty() { + continue; + } + let bytes = git_bytes( + attempt, + root, + "raw-working-hashes", + crate::git_metadata::raw_hash_arguments(&present), + )?; + hashes.extend( + crate::git_metadata::raw_hashes(&present, &bytes) + .map_err(|message| error(78, message))?, + ); + } + Ok(hashes) +} + +/// Refuse repository-controlled reviewer state before any external tool is started. +pub(super) fn refuse_tracked_workspace( + attempt: &mut Attempt<'_>, + root: &Path, +) -> Result<(), GateError> { + let bytes = git_bytes( + attempt, + root, + "tracked-review-workspace", + vec![ + "ls-files".into(), + "--cached".into(), + "-z".into(), + "--".into(), + ".deepsec-gate".into(), + ], + )?; + if !bytes.is_empty() { + return Err(error(78, "tracked .deepsec-gate reviewer state is refused")); + } + Ok(()) +} + +/// Observe only the selected raw input bytes against their committed Git blobs. +pub(super) fn selected_dirty( + attempt: &mut Attempt<'_>, + root: &Path, + paths: &[String], +) -> Result { + let mut reference = BTreeMap::new(); + for chunk in paths.chunks(64) { + let bytes = git_bytes( + attempt, + root, + "selected-reference-tree", + crate::git_metadata::tree_arguments("HEAD", chunk), + )?; + reference.extend( + crate::git_metadata::tree_entries(&bytes).map_err(|message| error(78, message))?, + ); + } + let current = working_hashes(attempt, root, paths)?; + Ok(paths + .iter() + .any(|p| reference.get(p).map(|e| &e.object) != current.get(p))) +} + pub(super) fn select( options: &DeepsecOptions, files: Option<&Path>, @@ -75,7 +216,7 @@ pub(super) fn select( read_bounded(files, 8 * 1024 * 1024)? } } else { - let mut args: Vec = if options.full || options.scan_only { + let args: Vec = if options.full || options.scan_only { vec![ "ls-files", "-z", @@ -87,29 +228,36 @@ pub(super) fn select( .map(str::to_owned) .collect() } else { - vec!["diff", "--name-only", "-z", "--diff-filter=AMRC"] - .into_iter() - .map(str::to_owned) - .collect() + Vec::new() }; - if options.diff_staged { - args.push("--cached".into()); - } - if options.diff_working { - args.push("HEAD".into()); - } - if let Some(reference) = &options.diff { - if reference.starts_with('-') { - return Err(error(78, "diff reference must not be a Git option")); + let mut bytes = if !args.is_empty() { + let mut args = args; + args.push("--".into()); + git_bytes(attempt, root, "source-selection", args)? + } else { + let base = tree(attempt, root, options.diff.as_deref().unwrap_or("HEAD"))?; + let indexed = index(attempt, root)?; + let selected: Vec = if options.diff_staged { + indexed + .iter() + .filter(|(p, e)| base.get(*p) != Some(*e)) + .map(|(p, _)| p.clone()) + .collect() + } else { + let paths: Vec<_> = indexed.keys().cloned().collect(); + working_hashes(attempt, root, &paths)? + .into_iter() + .filter(|(p, hash)| base.get(p).map(|e| &e.object) != Some(hash)) + .map(|(p, _)| p) + .collect() + }; + let mut out = Vec::new(); + for path in selected { + out.extend(path.as_bytes()); + out.push(0); } - args.push(reference.clone()); - } - args.push("--".into()); - let (rc, mut bytes) = - attempt.command("source-selection", "git", args, root, false, false)?; - if rc != 0 { - return Err(error(78, "could not resolve review source selection")); - } + out + }; if options.diff_working { let (rc, more) = attempt.command( "untracked-selection", @@ -146,19 +294,13 @@ pub(super) fn select( confined(root, path)?; } if options.diff_staged { - let (rc, bytes) = attempt.command( - "staged-byte-parity", - "git", - vec!["diff", "--name-only", "-z", "--"] - .into_iter() - .map(str::to_owned) - .collect(), - root, - false, - false, - )?; - let changed = String::from_utf8(bytes).map_err(|_| error(78, "Git paths must be UTF-8"))?; - if rc != 0 || changed.split('\0').any(|p| paths.contains(p)) { + let indexed = index(attempt, root)?; + let selected: Vec<_> = paths.iter().cloned().collect(); + let working = working_hashes(attempt, root, &selected)?; + if paths + .iter() + .any(|p| indexed.get(p).map(|e| &e.object) != working.get(p)) + { return Err(error( 78, "staged inputs differ from working-tree bytes; review an exact index checkout", @@ -292,7 +434,7 @@ pub(super) fn validate_review( if entry["refusal"]["refused"].as_bool() != Some(false) || entry["refusal"]["skipped"] .as_array() - .is_some_and(|s| !s.is_empty()) + .is_none_or(|s| !s.is_empty()) { return Err(error( 70, diff --git a/src/evaluate.rs b/src/evaluate.rs index 536c3d3..acd2798 100644 --- a/src/evaluate.rs +++ b/src/evaluate.rs @@ -308,6 +308,10 @@ fn assessment_binding( subject == &plan.subject && claimed == digest, "assessment plan/subject mismatch", )?; + crate::require( + context_limits(plan, context).is_empty(), + "assessment no longer binds to the current repository, configuration, inputs or revision ancestry", + )?; artifact_shape(artifact)?; crate::require( context.verified.contains(artifact), @@ -529,6 +533,11 @@ fn expectation_report( /// one attempt per check: historical attempts belong in the archive, not an /// ambiguous bag from which the evaluator silently chooses the greenest result. /// Invalid input is reported as an error; missing required evidence never passes. +/// +/// Deadlines use the runner's monotonic `elapsed_ms`; freshness and observation +/// ordering use Unix timestamps. Wall-clock adjustments can make those durations +/// differ, so their equality is not required. These are caller-supplied evidence +/// fields, not authenticated clock readings or proof that an invocation ran. pub fn evaluate( plan: &QualityPlan, receipts: &[ExecutionReceipt], diff --git a/src/git_metadata.rs b/src/git_metadata.rs index b201f65..80c0522 100644 --- a/src/git_metadata.rs +++ b/src/git_metadata.rs @@ -1,6 +1,118 @@ //! Shared policy for read-only Git metadata inspection, not user build commands. use std::collections::BTreeMap; +/// Unfiltered tracked-file identity. Modes participate in index/tree parity. +#[derive(Debug, Clone, PartialEq, Eq)] +pub(crate) struct Entry { + pub mode: String, + pub object: String, +} + +/// List raw tree entries, optionally confined to explicitly selected paths. +pub(crate) fn tree_arguments(reference: &str, paths: &[String]) -> Vec { + let mut args = vec![ + "ls-tree".into(), + "-r".into(), + "-z".into(), + "--full-tree".into(), + reference.into(), + "--".into(), + ]; + args.extend(paths.iter().cloned()); + args +} + +/// Parse `ls-tree -z` without consulting attributes or invoking conversions. +pub(crate) fn tree_entries(bytes: &[u8]) -> Result, &'static str> { + let mut entries = BTreeMap::new(); + for row in bytes.split(|b| *b == 0).filter(|r| !r.is_empty()) { + let at = row + .iter() + .position(|b| *b == b'\t') + .ok_or("invalid Git tree record")?; + let meta = std::str::from_utf8(&row[..at]).map_err(|_| "invalid Git tree metadata")?; + let fields: Vec<_> = meta.split_whitespace().collect(); + if fields.len() != 3 { + return Err("invalid Git tree fields"); + } + if fields[1] != "blob" { + continue; + } + let path = std::str::from_utf8(&row[at + 1..]).map_err(|_| "Git path is not UTF-8")?; + if !crate::hex(fields[2], &[40, 64]) + || entries + .insert( + path.to_owned(), + Entry { + mode: fields[0].to_owned(), + object: fields[2].to_owned(), + }, + ) + .is_some() + { + return Err("invalid or duplicate Git tree object"); + } + } + Ok(entries) +} + +/// Parse `ls-files --stage -z`; unresolved index stages cannot attest parity. +pub(crate) fn index_entries(bytes: &[u8]) -> Result, &'static str> { + let mut entries = BTreeMap::new(); + for row in bytes.split(|b| *b == 0).filter(|r| !r.is_empty()) { + let at = row + .iter() + .position(|b| *b == b'\t') + .ok_or("invalid Git index record")?; + let meta = std::str::from_utf8(&row[..at]).map_err(|_| "invalid Git index metadata")?; + let fields: Vec<_> = meta.split_whitespace().collect(); + if fields.len() != 3 || fields[2] != "0" || !crate::hex(fields[1], &[40, 64]) { + return Err("invalid or unresolved Git index entry"); + } + if fields[0] == "160000" { + return Err("submodule index entries require an explicit file manifest"); + } + let path = std::str::from_utf8(&row[at + 1..]).map_err(|_| "Git path is not UTF-8")?; + if entries + .insert( + path.to_owned(), + Entry { + mode: fields[0].to_owned(), + object: fields[1].to_owned(), + }, + ) + .is_some() + { + return Err("duplicate Git index entry"); + } + } + Ok(entries) +} + +/// Explicitly bypass all attribute filters; never write a Git object. +pub(crate) fn raw_hash_arguments(paths: &[String]) -> Vec { + let mut args = vec!["hash-object".into(), "--no-filters".into(), "--".into()]; + args.extend(paths.iter().cloned()); + args +} + +/// Bind ordered raw hashes to the paths passed to `hash-object`. +pub(crate) fn raw_hashes( + paths: &[String], + bytes: &[u8], +) -> Result, &'static str> { + let text = std::str::from_utf8(bytes).map_err(|_| "Git object hashes are not UTF-8")?; + let hashes: Vec<_> = text.lines().collect(); + if hashes.len() != paths.len() || hashes.iter().any(|h| !crate::hex(h, &[40, 64])) { + return Err("Git raw hash count or identity differs"); + } + Ok(paths + .iter() + .cloned() + .zip(hashes.into_iter().map(str::to_owned)) + .collect()) +} + pub(crate) fn prefix() -> Vec { [ "--no-pager", diff --git a/src/process.rs b/src/process.rs index 62e8766..671fa6f 100644 --- a/src/process.rs +++ b/src/process.rs @@ -6,12 +6,20 @@ use crate::plan::Invocation; use std::fs::{self, File, OpenOptions}; -use std::io::{self, Read, Write}; +use std::io; +#[cfg(all(target_os = "linux", not(target_env = "uclibc")))] +use std::io::{Read, Write}; use std::path::{Path, PathBuf}; +#[cfg(all(target_os = "linux", not(target_env = "uclibc")))] use std::process::{Command, Stdio}; +#[cfg(all(target_os = "linux", not(target_env = "uclibc")))] use std::sync::Arc; -use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU64, Ordering}; +use std::sync::atomic::AtomicBool; +#[cfg(all(target_os = "linux", not(target_env = "uclibc")))] +use std::sync::atomic::{AtomicU8, AtomicU64, Ordering}; +#[cfg(all(target_os = "linux", not(target_env = "uclibc")))] use std::thread; +#[cfg(all(target_os = "linux", not(target_env = "uclibc")))] use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH}; /// Why an invocation finished. A normal exit may still have a nonzero code. @@ -54,6 +62,7 @@ pub struct CapturedRun { pub error: Option, } +#[cfg(all(target_os = "linux", not(target_env = "uclibc")))] fn unix_now() -> u64 { SystemTime::now() .duration_since(UNIX_EPOCH) @@ -130,7 +139,7 @@ pub fn private_file(path: &Path) -> io::Result { options.open(path) } -#[cfg(unix)] +#[cfg(all(target_os = "linux", not(target_env = "uclibc")))] fn capture( mut input: R, mut output: File, @@ -184,16 +193,107 @@ fn capture( }) } -#[cfg(unix)] -fn signal_group(pid: u32, signal: nix::sys::signal::Signal) { - if let Ok(pid) = i32::try_from(pid) - && pid > 1 +#[cfg(all(target_os = "linux", not(target_env = "uclibc")))] +fn signal_owned_group( + child: &mut std::process::Child, + signal: nix::sys::signal::Signal, +) -> io::Result<()> { + // WNOWAIT proves this child still belongs to us and keeps its PID allocated. + // In particular ECHILD must never fall through to a numeric group signal. + leader_exited(child)?; + let pid = i32::try_from(child.id()).map_err(|_| io::Error::other("invalid child PID"))?; + nix::sys::signal::killpg(nix::unistd::Pid::from_raw(pid), signal).map_err(io::Error::from) +} + +#[cfg(all(target_os = "linux", not(target_env = "uclibc")))] +fn leader_exited(child: &mut std::process::Child) -> io::Result { + use nix::sys::wait::{Id, WaitPidFlag, WaitStatus, waitid}; + use nix::unistd::Pid; + let pid = i32::try_from(child.id()).map_err(|_| io::Error::other("invalid child PID"))?; + if pid <= 1 { + return Err(io::Error::other("invalid child PID")); + } + let pid = Pid::from_raw(pid); + match waitid( + Id::Pid(pid), + WaitPidFlag::WEXITED | WaitPidFlag::WNOHANG | WaitPidFlag::WNOWAIT, + ) + .map_err(io::Error::from)? { - let _ = nix::sys::signal::killpg(nix::unistd::Pid::from_raw(pid), signal); + WaitStatus::StillAlive => Ok(false), + WaitStatus::Exited(observed, _) | WaitStatus::Signaled(observed, _, _) + if observed == pid => + { + Ok(true) + } + _ => Err(io::Error::other("unexpected child wait state")), + } +} + +#[cfg(all(test, target_os = "linux", not(target_env = "uclibc")))] +mod lifecycle_tests { + use super::*; + use nix::unistd::{Pid, getpgid}; + use std::os::unix::process::CommandExt; + + #[test] + fn observed_exit_retains_leader_identity_until_explicit_reap() { + let mut child = Command::new("sh") + .args(["-c", "exit 7"]) + .process_group(0) + .spawn() + .unwrap(); + let pid = Pid::from_raw(i32::try_from(child.id()).unwrap()); + let deadline = Instant::now() + Duration::from_secs(2); + while !leader_exited(&mut child).unwrap() { + assert!(Instant::now() < deadline, "fixture child did not exit"); + thread::sleep(Duration::from_millis(5)); + } + let held_group = getpgid(Some(pid)); + let status = child.wait().unwrap(); + assert_eq!(status.code(), Some(7)); + assert_eq!( + held_group, + Ok(pid), + "exit observation must not release the PID" + ); + assert_eq!(getpgid(Some(pid)), Err(nix::errno::Errno::ESRCH)); + } + + #[test] + fn lost_child_ownership_prevents_signalling_a_surviving_group() { + let mut leader = Command::new("sh") + .args(["-c", "read line; exit 0"]) + .process_group(0) + .stdin(Stdio::piped()) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .spawn() + .unwrap(); + let group = i32::try_from(leader.id()).unwrap(); + let mut member = Command::new("sleep") + .arg("30") + .process_group(group) + .stdin(Stdio::null()) + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .spawn() + .unwrap(); + drop(leader.stdin.take()); + leader.wait().unwrap(); // Simulate an incompatible external reaper. + let signal = signal_owned_group(&mut leader, nix::sys::signal::Signal::SIGKILL); + let survived = member.try_wait().unwrap().is_none(); + let _ = member.kill(); + member.wait().unwrap(); + assert_eq!( + signal.unwrap_err().raw_os_error(), + Some(nix::errno::Errno::ECHILD as i32) + ); + assert!(survived, "ownership failure must prevent any group signal"); } } -#[cfg(unix)] +#[cfg(all(target_os = "linux", not(target_env = "uclibc")))] fn group_probe(result: Result<(), nix::errno::Errno>) -> io::Result { match result { Ok(()) => Ok(true), @@ -202,7 +302,7 @@ fn group_probe(result: Result<(), nix::errno::Errno>) -> io::Result { } } -#[cfg(unix)] +#[cfg(all(target_os = "linux", not(target_env = "uclibc")))] fn group_running(pid: u32, deadline: Instant) -> io::Result { use nix::sys::signal::killpg; use nix::unistd::Pid; @@ -213,20 +313,11 @@ fn group_running(pid: u32, deadline: Instant) -> io::Result { if !group_probe(killpg(Pid::from_raw(group), None))? { return Ok(false); } - #[cfg(target_os = "linux")] - { - // Signal 0 proves existence, not execution: zombies still occupy groups. - linux_proc::group_running(group, deadline) - } - #[cfg(not(target_os = "linux"))] - { - let _ = deadline; - // Without a supported state observer, an existing group remains unsafe. - Ok(true) - } + // Signal 0 proves existence, not execution: zombies still occupy groups. + linux_proc::group_running(group, deadline) } -#[cfg(target_os = "linux")] +#[cfg(all(target_os = "linux", not(target_env = "uclibc")))] mod linux_proc { use super::*; use nix::unistd::{Pid, getpgid}; @@ -489,13 +580,17 @@ mod linux_proc { /// only the named variables that exist in the caller. Stdin is closed unless /// explicitly inherited for a transport such as Deepsec's `--files-from -`. /// -/// Unix execution uses a new process group and stops that group on interruption, -/// deadline, capture failure or lingering descendants. Non-Unix execution is -/// explicitly unsupported rather than claiming unimplemented child cleanup. +/// Linux execution uses a new process group and stops that group on interruption, +/// deadline, capture failure or lingering descendants. The leader remains +/// unreaped until every group signal is complete, preventing PID reuse during +/// cleanup. Platforms without this supported lifecycle (including Linux uClibc) +/// return [`io::ErrorKind::Unsupported`] before spawning a process. /// Linux excludes zombie/dead group members only after bounded, unrestricted /// proc observations, including their threads. Unknown or unreadable membership -/// remains a failure. Other Unix systems conservatively reject any surviving -/// process group, including unreaped zombies. No subreaper state is changed. +/// remains a failure. No subreaper state is changed. The caller must not install +/// competing process-wide child reapers, ignore `SIGCHLD`, or use `SA_NOCLDWAIT`: +/// those break this runner's ownership of its children. Lost ownership prevents +/// further group signals and is reported as capture failure, never completion. pub fn run_command( invocation: &Invocation, root: &Path, @@ -523,7 +618,7 @@ pub(crate) fn run_command_with_env( inherit_stdin: bool, overrides: &std::collections::BTreeMap, ) -> io::Result { - #[cfg(not(unix))] + #[cfg(not(all(target_os = "linux", not(target_env = "uclibc"))))] { let _ = ( invocation, @@ -535,10 +630,10 @@ pub(crate) fn run_command_with_env( ); Err(io::Error::new( io::ErrorKind::Unsupported, - "bounded process groups require Unix", + "bounded execution requires Linux with supported non-reaping child observation", )) } - #[cfg(unix)] + #[cfg(all(target_os = "linux", not(target_env = "uclibc")))] { use nix::sys::signal::Signal; use std::os::unix::process::{CommandExt, ExitStatusExt}; @@ -627,7 +722,8 @@ pub(crate) fn run_command_with_env( stop_capture.clone(), invocation.max_output_bytes, ); - let mut status = None; + let mut exited = false; + let mut owns_child = true; result.termination = loop { if cancelled.load(Ordering::SeqCst) { break Termination::Interrupted; @@ -638,13 +734,14 @@ pub(crate) fn run_command_with_env( if fault.load(Ordering::SeqCst) != 0 { break Termination::CaptureFailed; } - match child.try_wait() { - Ok(Some(exit)) => { - status = Some(exit); + match leader_exited(&mut child) { + Ok(true) => { + exited = true; break Termination::Completed; } - Ok(None) => thread::sleep(Duration::from_millis(10)), + Ok(false) => thread::sleep(Duration::from_millis(10)), Err(_) => { + owns_child = false; result.error = Some("could not observe process exit".into()); break Termination::CaptureFailed; } @@ -683,22 +780,39 @@ pub(crate) fn run_command_with_env( } } if result.termination != Termination::Completed { - signal_group(pid, Signal::SIGINT); + if owns_child && signal_owned_group(&mut child, Signal::SIGINT).is_err() { + owns_child = false; + result.error = Some("could not safely signal the owned process group".into()); + } let grace = Instant::now(); - while grace.elapsed() < Duration::from_millis(250) { - if status.is_none() { - status = child.try_wait().ok().flatten(); + while owns_child && grace.elapsed() < Duration::from_millis(250) { + if !exited { + match leader_exited(&mut child) { + Ok(done) => exited = done, + Err(_) => { + owns_child = false; + result.error = + Some("lost ownership of the process group leader".into()); + break; + } + } } - if stdout.is_finished() && stderr.is_finished() && status.is_some() { + if stdout.is_finished() && stderr.is_finished() && exited { break; } thread::sleep(Duration::from_millis(10)); } - signal_group(pid, Signal::SIGKILL); + if owns_child && signal_owned_group(&mut child, Signal::SIGKILL).is_err() { + owns_child = false; + result.error = Some("could not safely stop the owned process group".into()); + } stop_capture.store(true, Ordering::SeqCst); } + // This is the only reaping point, after the final possible group signal. + let status = owns_child.then(|| child.wait().ok()).flatten(); if status.is_none() { - status = child.wait().ok(); + result.termination = Termination::CaptureFailed; + result.error = Some("could not reap the owned process group leader".into()); } for capture in [stdout, stderr] { if !matches!(capture.join(), Ok(Ok(()))) { diff --git a/tests/core.rs b/tests/core.rs index 2593786..e0f6820 100644 --- a/tests/core.rs +++ b/tests/core.rs @@ -599,6 +599,7 @@ fn a_manual_expectation_does_not_need_a_fabricated_executable_scenario() { e.stabilizer = None; e.positive_control = None; plan.expectations.push(e); + plan.policy.max_age_ms = None; plan.validate().unwrap(); let mut verified = VerifiedArtifacts::default(); let run = receipt(&plan, "main", &mut verified); @@ -616,7 +617,89 @@ fn a_manual_expectation_does_not_need_a_fabricated_executable_scenario() { }]; let mut context = EvaluationContext::new(1020, &plan.subject, &verified); context.manual_observations = &observations; - assert!(evaluate(&plan, &[run], &context).passed()); + let runs = [run]; + assert!(evaluate(&plan, &runs, &context).passed()); + for case in 0..4 { + let mut current = plan.subject.clone(); + match case { + 0 => current.repository = "another repository".into(), + 1 => current.configuration = "different features".into(), + 2 => current.inputs[0].sha256 = sha256(b"changed implementation"), + _ => current.revision = "b".repeat(40), + } + let mut context = EvaluationContext::new(1020, ¤t, &verified); + context.manual_observations = &observations; + let report = evaluate(&plan, &runs, &context); + assert_eq!(report.outcome, GateOutcome::Incomplete, "case {case}"); + assert_eq!( + report.expectations[0].outcome, + CheckOutcome::Inconclusive, + "manual observation must not support a changed subject: case {case}" + ); + assert!( + !report.expectations[0] + .reasons + .iter() + .any(|reason| reason.contains("observer supports")), + "stale evidence must not retain a supporting interpretation" + ); + } + let mut current = plan.subject.clone(); + current.revision = "b".repeat(40); + let ancestry = [plan.subject.revision.clone()]; + let mut context = EvaluationContext::new(1020, ¤t, &verified); + context.manual_observations = &observations; + context.ancestor_revisions = &ancestry; + assert!(evaluate(&plan, &runs, &context).passed()); +} + +#[test] +fn stale_audits_cannot_support_or_contradict_the_current_subject() { + let mut plan = plan(); + let mut e = expectation(); + e.independent_audit = true; + plan.expectations.push(e); + let mut verified = VerifiedArtifacts::default(); + let runs = ["main", "control", "probe"].map(|id| receipt(&plan, id, &mut verified)); + let valid = audit(&plan, &mut verified); + let mut current = plan.subject.clone(); + current.inputs[0].sha256 = sha256(b"changed implementation"); + for verdict in [AuditVerdict::Supported, AuditVerdict::Contradicted] { + let mut assessment = valid.clone(); + assessment.verdict = verdict; + let audits = [assessment]; + let mut context = EvaluationContext::new(1020, ¤t, &verified); + context.audits = &audits; + let report = evaluate(&plan, &runs, &context); + assert_eq!(report.outcome, GateOutcome::Incomplete); + assert_eq!(report.expectations[0].outcome, CheckOutcome::Inconclusive); + assert!( + !report.expectations[0].reasons.iter().any(|reason| { + reason.contains("supports the scoped claim") + || reason.contains("recorded a counterexample") + }), + "a verdict about old inputs must not be credited to current inputs" + ); + } +} + +#[test] +fn deadlines_use_monotonic_duration_instead_of_wall_clock_span() { + let plan = plan(); + let mut verified = VerifiedArtifacts::default(); + let mut run = receipt(&plan, "main", &mut verified); + for (finished, elapsed) in [(6000, 10), (1001, 1000)] { + run.finished_at_ms = finished; + run.elapsed_ms = elapsed; + let context = EvaluationContext::new(finished + 10, &plan.subject, &verified); + assert!(evaluate(&plan, std::slice::from_ref(&run), &context).passed()); + } + run.elapsed_ms = plan.checks[0].invocation.timeout_ms + 1; + let context = EvaluationContext::new(run.finished_at_ms + 10, &plan.subject, &verified); + assert_eq!( + evaluate(&plan, &[run], &context).outcome, + GateOutcome::Error + ); } #[test] diff --git a/tests/deepsec.rs b/tests/deepsec.rs index 286cd5d..17da76e 100644 --- a/tests/deepsec.rs +++ b/tests/deepsec.rs @@ -1,5 +1,5 @@ //! External reviewer protocol controls using a model-free executable double. -#![cfg(all(unix, feature = "cli"))] +#![cfg(all(target_os = "linux", not(target_env = "uclibc"), feature = "cli"))] use serde_json::{Value, json}; use std::fs; use std::path::PathBuf; @@ -131,6 +131,152 @@ fn metadata_does_not_execute_repository_fsmonitor() { ); } +#[test] +fn dirty_metadata_and_working_selection_do_not_execute_clean_filters() { + for working_selection in [false, true] { + let f = Fixture::new("pass"); + assert!( + Command::new("git") + .args([ + "config", + "filter.fixture.clean", + "sh -c 'touch FILTER_EXECUTED; cat'" + ]) + .current_dir(&f.root) + .status() + .unwrap() + .success() + ); + fs::write(f.root.join(".gitattributes"), "input.py filter=fixture\n").unwrap(); + fs::write(f.root.join("input.py"), "print('changed fixture')\n").unwrap(); + assert!(!f.root.join("FILTER_EXECUTED").exists()); + let output = if working_selection { + f.run(&["--diff-working"], json!({"max_duration":"10s"})) + } else { + f.gate() + }; + assert_eq!( + output.status.code(), + Some(0), + "{} {}", + String::from_utf8_lossy(&output.stdout), + String::from_utf8_lossy(&output.stderr) + ); + assert!( + !f.root.join("FILTER_EXECUTED").exists(), + "read-only dirty/selection metadata invoked a repository clean filter (working_selection={working_selection})" + ); + } +} + +#[test] +fn selected_dirty_scope_does_not_inspect_unselected_filter_managed_assets() { + let f = Fixture::new("pass"); + fs::write(f.root.join("asset.bin"), "version https://git-lfs.github.com/spec/v1\noid sha256:0000000000000000000000000000000000000000000000000000000000000000\nsize 34603008\n").unwrap(); + for args in [ + vec!["add", "asset.bin"], + vec![ + "-c", + "user.name=Fixture", + "-c", + "user.email=fixture@example.invalid", + "commit", + "-qm", + "asset pointer", + ], + ] { + assert!( + Command::new("git") + .args(args) + .current_dir(&f.root) + .status() + .unwrap() + .success() + ); + } + assert!( + Command::new("git") + .args([ + "config", + "filter.lfs.clean", + "sh -c 'touch UNEXPECTED_LFS; cat'" + ]) + .current_dir(&f.root) + .status() + .unwrap() + .success() + ); + fs::write(f.root.join(".gitattributes"), "asset.bin filter=lfs\n").unwrap(); + fs::File::create(f.root.join("asset.bin")) + .unwrap() + .set_len(33 * 1024 * 1024) + .unwrap(); + let output = f.gate(); + assert_eq!( + output.status.code(), + Some(0), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + assert!(!f.root.join("UNEXPECTED_LFS").exists()); + let receipt = f.receipt(); + assert_eq!(receipt["dirty_scope"], "selected-inputs"); + assert_eq!(receipt["dirty"], false); + assert_eq!( + receipt["observed_review"]["observed_files"], + json!(["input.py"]) + ); +} + +#[test] +fn tracked_review_workspace_is_refused_before_external_reviewer_version_probe() { + let f = Fixture::new("pass"); + fs::create_dir(f.root.join(".deepsec-gate")).unwrap(); + let ignored = b"# tracked fixture sentinel\n*\n"; + let configuration = b"// tracked configuration sentinel\nexport default {};\n"; + fs::write(f.root.join(".deepsec-gate/.gitignore"), ignored).unwrap(); + fs::write( + f.root.join(".deepsec-gate/deepsec.config.mjs"), + configuration, + ) + .unwrap(); + assert!( + Command::new("git") + .args([ + "add", + "-f", + ".deepsec-gate/.gitignore", + ".deepsec-gate/deepsec.config.mjs" + ]) + .current_dir(&f.root) + .status() + .unwrap() + .success() + ); + fs::write( + f.bin.join("deepsec"), + format!( + "#!/bin/sh\ntouch '{}'\nexit 0\n", + f.root.join("VERSION_EXECUTED").display() + ), + ) + .unwrap(); + let output = f.gate(); + assert_eq!(output.status.code(), Some(78)); + assert!( + !f.root.join("VERSION_EXECUTED").exists(), + "tracked state reached the external reviewer" + ); + assert_eq!( + fs::read(f.root.join(".deepsec-gate/.gitignore")).unwrap(), + ignored + ); + assert_eq!( + fs::read(f.root.join(".deepsec-gate/deepsec.config.mjs")).unwrap(), + configuration + ); +} + #[test] fn review_state_refuses_nested_symlinks_before_external_tools() { use std::os::unix::fs::symlink; @@ -152,6 +298,37 @@ fn review_state_refuses_nested_symlinks_before_external_tools() { assert_eq!(fs::read_dir(outside).unwrap().count(), 0); } } + +#[test] +fn workspace_root_rejects_unmanaged_loader_inputs() { + for name in [".env", "node_modules", "deepsec.config.ts"] { + let f = Fixture::new("pass"); + let state = f.root.join(".deepsec-gate"); + fs::create_dir(&state).unwrap(); + fs::write(state.join(name), "untrusted loader input").unwrap(); + let output = f.gate(); + assert_eq!(output.status.code(), Some(78), "{name}"); + } +} + +#[test] +fn historical_reports_are_not_revisited_as_active_reviewer_state() { + use std::os::unix::fs::symlink; + let f = Fixture::new("pass"); + let old = f.root.join(".deepsec-gate/reports/archived"); + fs::create_dir_all(&old).unwrap(); + let outside = f._temp.path().join("old-capture"); + fs::write(&outside, "preserved evidence").unwrap(); + symlink(&outside, old.join("old-output")).unwrap(); + let output = f.gate(); + assert_eq!( + output.status.code(), + Some(0), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + assert_eq!(fs::read_to_string(outside).unwrap(), "preserved evidence"); +} #[test] fn no_empty_partial_or_ambiguous_review_can_pass() { for case in [ @@ -161,6 +338,9 @@ fn no_empty_partial_or_ambiguous_review_can_pass() { "refused", "partial", "unknown-refusal", + "missing-skipped", + "null-skipped", + "scalar-skipped", "zero-output", "missing-model", "stale", diff --git a/tests/fixtures/deepsec.py b/tests/fixtures/deepsec.py index a68526e..9aae1a7 100644 --- a/tests/fixtures/deepsec.py +++ b/tests/fixtures/deepsec.py @@ -27,7 +27,10 @@ def opt(name,default=None): if case=='incomplete':run['phase']='running' (data/'runs'/f'{run_id}.json').write_text(json.dumps(run)) for path in paths: - entry={'runId':run_id,'model':'fixture-model','agentType':'fixture-agent','refusal':{'refused':False},'usage':{'outputTokens':42}} + entry={'runId':run_id,'model':'fixture-model','agentType':'fixture-agent','refusal':{'refused':False,'skipped':[]},'usage':{'outputTokens':42}} + if case=='missing-skipped':del entry['refusal']['skipped'] + if case=='null-skipped':entry['refusal']['skipped']=None + if case=='scalar-skipped':entry['refusal']['skipped']='unknown' if case=='refused':entry['refusal']['refused']=True if case=='partial':entry['refusal']['skipped']=[{'filePath':path,'reason':'fixture'}] if case=='unknown-refusal':del entry['refusal'] diff --git a/tests/native_cli.rs b/tests/native_cli.rs index f408033..dbdca2a 100644 --- a/tests/native_cli.rs +++ b/tests/native_cli.rs @@ -1,5 +1,5 @@ //! Executed native CLI contracts using local temporary Git fixtures only. -#![cfg(all(unix, feature = "cli"))] +#![cfg(all(target_os = "linux", not(target_env = "uclibc"), feature = "cli"))] use std::fs; use std::path::Path; diff --git a/tests/process.rs b/tests/process.rs index ae14161..c5f99a6 100644 --- a/tests/process.rs +++ b/tests/process.rs @@ -1,5 +1,5 @@ //! Executable process-boundary controls. -#![cfg(all(unix, feature = "process"))] +#![cfg(all(target_os = "linux", not(target_env = "uclibc"), feature = "process"))] use std::fs; use std::sync::atomic::{AtomicBool, Ordering}; From a92d0cdaa931e1123047626ed87e63c47e383fcf Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 3 Nov 2026 12:06:33 +0000 Subject: [PATCH 16/16] Verify final release architecture and refresh generated diagrams --- docs/adr/0001-portable-quality-contract.md | 6 +- .../0002-specialist-upstream-boundaries.md | 2 +- docs/diagrams/README.md | 8 +- docs/diagrams/generated/_index.json | 2 +- docs/diagrams/generated/_overview.md | 10 +- docs/diagrams/generated/src/cli.rs.md | 39 +++---- docs/diagrams/generated/src/deepsec.rs.md | 72 ++++++++---- .../generated/src/deepsec_evidence.rs.md | 108 +++++++++++++++--- docs/diagrams/generated/src/evaluate.rs.md | 10 +- .../diagrams/generated/src/git_metadata.rs.md | 15 ++- docs/diagrams/generated/src/process.rs.md | 28 +++-- 11 files changed, 209 insertions(+), 91 deletions(-) diff --git a/docs/adr/0001-portable-quality-contract.md b/docs/adr/0001-portable-quality-contract.md index 546bc10..df4e602 100644 --- a/docs/adr/0001-portable-quality-contract.md +++ b/docs/adr/0001-portable-quality-contract.md @@ -3,7 +3,7 @@ id: ADR-0001 title: Portable quality contracts with explicit execution adapters status: accepted date: 2026-11-03 -verified_commit: 2c5a625ce245be2a5ec2f0b30633d708b50afb9e +verified_commit: e3306776ebab083a7842b02ce4fec4e0a2bbc77c verified_paths: - src/plan.rs - src/evidence.rs @@ -36,7 +36,7 @@ identifiers are caller declarations, explicitly labelled as unverified when no current-subject attestation is supplied. Include configuration files in the selected inputs when their exact bytes must be checked automatically. -Optional Unix process/CLI adapters execute explicit commands with private captures, +Optional Linux process/CLI adapters execute explicit commands with private captures, deadlines and process-group cancellation. Read-only evaluation never executes an imported receipt's command. Fixed Git metadata probes use the same bounded runner, remove ambient Git redirection and avoid repository clean filters. This is not an @@ -52,7 +52,7 @@ optional search/index tools are consumers. A prose-only extraction would preserve the original gap between requested checks and executable evidence. A new agent orchestration runtime would duplicate host execution and custody services. The selected boundary supports a pure library, -portable foreground CLI and independently maintained host adapters. +host-neutral foreground CLI and independently maintained host adapters. Generic command receipts cannot prove test coverage or claim that a model inspected all relevant code. Independent audits and manual observations remain explicit, diff --git a/docs/adr/0002-specialist-upstream-boundaries.md b/docs/adr/0002-specialist-upstream-boundaries.md index c8ce276..983ed88 100644 --- a/docs/adr/0002-specialist-upstream-boundaries.md +++ b/docs/adr/0002-specialist-upstream-boundaries.md @@ -4,7 +4,7 @@ title: Consume specialist reviewers through versioned upstream contracts status: accepted date: 2026-11-03 depends_on: [ADR-0001] -verified_commit: 2c5a625ce245be2a5ec2f0b30633d708b50afb9e +verified_commit: e3306776ebab083a7842b02ce4fec4e0a2bbc77c verified_paths: - src/deepsec.rs - src/deepsec_evidence.rs diff --git a/docs/diagrams/README.md b/docs/diagrams/README.md index 0355979..c082bc8 100644 --- a/docs/diagrams/README.md +++ b/docs/diagrams/README.md @@ -20,16 +20,16 @@ consumption. Source extraction, Mermaid rendering and runtime verification are separate observations. The following authored view is verified against source at -`2c5a625ce245be2a5ec2f0b30633d708b50afb9e`: `src/cli.rs:1101`, -`src/plan.rs:295`, `src/evaluate.rs:532`, `src/process.rs:499`, -`src/deepsec.rs:623` and `src/deepsec_evidence.rs:220`. +`e3306776ebab083a7842b02ce4fec4e0a2bbc77c`: `src/cli.rs:1084`, +`src/plan.rs:295`, `src/evaluate.rs:541`, `src/process.rs:594`, +`src/deepsec.rs:645` and `src/deepsec_evidence.rs:362`. ```mermaid flowchart TD User[Explicit CLI operation] --> Plan[Typed quality plan] Plan --> Admit[Validate references and aggregate limits] Admit --> Run[Run selected checks] - Run --> Process[Bounded Unix process group] + Run --> Process[Bounded Linux process group] Process --> Receipt[Private execution receipts and raw captures] Receipt --> Verify[Verify artifact bytes and current source] Verify --> Gate[Evaluate checks and expectations] diff --git a/docs/diagrams/generated/_index.json b/docs/diagrams/generated/_index.json index fa0efed..9744fc5 100644 --- a/docs/diagrams/generated/_index.json +++ b/docs/diagrams/generated/_index.json @@ -1 +1 @@ -{"schema_version":2,"generator":"sealmap-corpus 0.4.0","codebase":"visioncraft","stats":{"files":10,"symbols":168,"relations":632,"flows":80,"calls":543},"documents":[{"source":"src/cli.rs","document":"src/cli.rs.md","module":"sym:cargo visioncraft . cli/","source_hash":"blake3:e5a287dcb11e681724fa694daeace991975ed75a6cc4cf342d3328a778ce0c6d","document_hash":"blake3:c3b266d36b5d8ccc0d932770c364a7e627ea91c044344b40fe7db175a310670d","fragments":[{"id":"structure:src/cli.rs","kind":"structure","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/","span":{"start_line":1,"start_col":1,"end_line":1135,"end_col":1},"sig_hash":"blake3-16:a91e60562b65dab9be5fcfdd480a0025","body_hash":"blake3-16:00bd56919309e773ec512fe9b51e3363","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft . cli/Cli#","sym:cargo visioncraft . cli/CliError#","sym:cargo visioncraft . cli/ContextFile#","sym:cargo visioncraft . cli/EvaluateOptions#","sym:cargo visioncraft . cli/ExpectationCommand#","sym:cargo visioncraft . cli/FamilyDeclaration#","sym:cargo visioncraft . cli/GateCommand#","sym:cargo visioncraft . cli/GitOutput#","sym:cargo visioncraft . cli/InitOptions#","sym:cargo visioncraft . cli/Operation#","sym:cargo visioncraft . cli/PlanCommand#","sym:cargo visioncraft . cli/RunOptions#","sym:cargo visioncraft . cli/SnapshotInput#"],"hash":"blake3:cc028d12f950c3ae1e85c12d11800b79b52157876e4bc9dd1614e6a982724168"},{"id":"sym:cargo visioncraft . cli/confined().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/confined().","span":{"start_line":225,"start_col":1,"end_line":251,"end_col":2},"sig_hash":"blake3-16:0f062b609af0623484ee4a8f3ce0791c","body_hash":"blake3-16:4d6d3d8c0f03abdfbfa2e19fad43f067","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":229},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":230},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":235},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":240},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":248}],"hash":"blake3:10134bbd7624f9bdd4c0c962084ddf99406fd07aaff1c112d8e6fde98e6256d2"},{"id":"sym:cargo visioncraft . cli/read_explicit().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/read_explicit().","span":{"start_line":273,"start_col":1,"end_line":285,"end_col":2},"sig_hash":"blake3-16:0135480ca8cad65a15367671ed65406d","body_hash":"blake3-16:2795f0c0dbe9df2e76d5b564e531760e","participants":["sym:cargo visioncraft . cli/"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":274},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":282},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":283,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":284}],"hash":"blake3:ea44521ca2c9580a30bcd4324260bf263e6d214f80c0579223fe16ef7cab9f86"},{"id":"sym:cargo visioncraft . cli/output_path().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/output_path().","span":{"start_line":287,"start_col":1,"end_line":312,"end_col":2},"sig_hash":"blake3-16:dbdb74d9394b0d29e9e3e8e51c008181","body_hash":"blake3-16:ca6d64c44631f2c0ee6c2ac804186a41","participants":["sym:cargo visioncraft . cli/"],"calls":[{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":296},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":302},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":304},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":306},{"target":"sym:cargo visioncraft . cli/io_error().","confidence":"exact","line":308}],"hash":"blake3:16ae04e0f4143479ef97deccd15f1e0d6c9c12d1f16c3de82ed63430b15466ec"},{"id":"sym:cargo visioncraft . cli/write_new().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/write_new().","span":{"start_line":314,"start_col":1,"end_line":326,"end_col":2},"sig_hash":"blake3-16:2d4d3f36490d72b3f6dc2d027eca4f3e","body_hash":"blake3-16:697a3ac4de3c725a30cfdc25488b8f86","participants":["sym:cargo visioncraft . cli/","sym:extern tempfile"],"calls":[{"target":"sym:cargo visioncraft . cli/output_path().","confidence":"exact","line":315,"expands":"sym:cargo visioncraft . cli/output_path()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":318},{"target":"sym:extern tempfile::NamedTempFile::new_in","confidence":"external","line":319},{"target":"sym:cargo visioncraft . cli/io_error().","confidence":"exact","line":324}],"hash":"blake3:457d2ebe0c5c2371326d12fd034f42e6ec1b554309aa824f919c052357d114df"},{"id":"sym:cargo visioncraft . cli/git().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/git().","span":{"start_line":345,"start_col":1,"end_line":405,"end_col":2},"sig_hash":"blake3-16:4841aa17643eae3fb5fe09d3badd3661","body_hash":"blake3-16:f6010aec4da04480c3e910c072d027ab","participants":["sym:cargo visioncraft . cli/","sym:extern tempfile","sym:cargo visioncraft . git_metadata/","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:extern tempfile::Builder::new","confidence":"external","line":346},{"target":"sym:extern tempfile::Builder::prefix","confidence":"external","line":347},{"target":"sym:extern tempfile::Builder::permissions","confidence":"external","line":351},{"target":"sym:extern tempfile::Builder::tempdir","confidence":"external","line":353},{"target":"sym:cargo visioncraft . git_metadata/prefix().","confidence":"exact","line":359},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":364},{"target":"sym:cargo visioncraft . git_metadata/fixed_environment().","confidence":"exact","line":372},{"target":"sym:cargo visioncraft . process/run_command_with_env().","confidence":"exact","line":383,"expands":"sym:cargo visioncraft . process/run_command_with_env()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":395},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":397},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":398},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":399},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":400}],"hash":"blake3:83e03825a35a5889cc5fdc8f48f354c078f2c26ce2c1f5b2a27c57c91d69ef20"},{"id":"sym:cargo visioncraft . cli/revision().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/revision().","span":{"start_line":407,"start_col":1,"end_line":417,"end_col":2},"sig_hash":"blake3-16:0b6fb7f218212ea850ac236d821d8a54","body_hash":"blake3-16:57f70fb943003d553d789a8ac8afdf57","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":408,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":410},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":413},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":414}],"hash":"blake3:6a47990d6e52a53cd8a184d578ac35266d83543a99f35ac8eb40a6ae358444e3"},{"id":"sym:cargo visioncraft . cli/selected_dirty().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/selected_dirty().","span":{"start_line":419,"start_col":1,"end_line":484,"end_col":2},"sig_hash":"blake3-16:466ae4a23ec9651aa81d4bed047fce21","body_hash":"blake3-16:60c71d02d369ba96d0e8ac250beb706a","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":424,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":426},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":437},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":439},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":445},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":452},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":453},{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":455,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":457},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":460},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":464},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":466},{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":468,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":470},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":472},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":474,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":475},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":479}],"hash":"blake3:453ed573926bd3366697d5f770d078d6675b2d10fc95e5d42b91b2998b8b86df"},{"id":"sym:cargo visioncraft . cli/inputs().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/inputs().","span":{"start_line":493,"start_col":1,"end_line":521,"end_col":2},"sig_hash":"blake3-16:ed0d5f7af2c90806f98bbe55046295b0","body_hash":"blake3-16:a4fe913978641a3fc470a6673895dbdd","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":496,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":499},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":499},{"target":"sym:cargo visioncraft . cli/io_error().","confidence":"exact","line":509},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":511}],"hash":"blake3:3f2dccdf84b13932d2d5f50d867c14fdcb3bccb66ede478c1abcba1fd56cc8a7"},{"id":"sym:cargo visioncraft . cli/source_snapshot().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/source_snapshot().","span":{"start_line":523,"start_col":1,"end_line":557,"end_col":2},"sig_hash":"blake3-16:99ceb13e4265b3151783ffc6a3e45c52","body_hash":"blake3-16:cbf9aee3425988e9536de14608e8da81","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:extern sealmap_corpus"],"calls":[{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":532,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":532},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":535},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":540},{"target":"sym:extern sealmap_corpus::review::Artifact::iter","confidence":"external","line":542},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":545},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":556}],"hash":"blake3:f3d87fe2bf48f895fb27ad21313f2b1c7930ba3db6156c76295df6bb381ab3a4"},{"id":"sym:cargo visioncraft . cli/init().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/init().","span":{"start_line":564,"start_col":1,"end_line":652,"end_col":2},"sig_hash":"blake3-16:b4e883cfce087fb3dfc81327eb4ad912","body_hash":"blake3-16:b5e11d29744c7e97abe293abd262f6ed","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":565},{"target":"sym:cargo visioncraft . cli/output_path().","confidence":"exact","line":566,"expands":"sym:cargo visioncraft . cli/output_path()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":570},{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":573},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":574},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":577,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":578,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/selected_dirty().","confidence":"exact","line":579,"expands":"sym:cargo visioncraft . cli/selected_dirty()."},{"target":"sym:cargo visioncraft . cli/source_snapshot().","confidence":"exact","line":581,"expands":"sym:cargo visioncraft . cli/source_snapshot()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":589},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":594},{"target":"sym:cargo visioncraft . plan/QualityPlan#validate().","confidence":"exact","line":634,"expands":"sym:cargo visioncraft . plan/QualityPlan#validate()."},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":635,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":636,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":637},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":640},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":642},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":643,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":645,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":647},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":647,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":648}],"hash":"blake3:2bd9ae15fbaff3cd2eec8f3f3539d22c3dd9870def20c2e0f278d9303ee76f01"},{"id":"sym:cargo visioncraft . cli/add_artifact().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/add_artifact().","span":{"start_line":654,"start_col":1,"end_line":662,"end_col":2},"sig_hash":"blake3-16:f0e71327596608de7e6b1f6a54853e2d","body_hash":"blake3-16:9b18aea04b32a8ac770134c2c7b25309","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . evidence/VerifiedArtifacts#"],"calls":[{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":659},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":660,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":660},{"target":"sym:cargo visioncraft . evidence/VerifiedArtifacts#insert().","confidence":"exact","line":661}],"hash":"blake3:9ab7e24505a5f71cd2e61508e0fabb0e233106589d756559b7851f0b72d83d88"},{"id":"sym:cargo visioncraft . cli/evidence_parent().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/evidence_parent().","span":{"start_line":674,"start_col":1,"end_line":685,"end_col":2},"sig_hash":"blake3-16:db2e97ad57784510b3ed00e2d46b651b","body_hash":"blake3-16:88b1ddfbb57f2b8c7f2a5d0b9bb1ffb9","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":675},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":676},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":682},{"target":"sym:cargo visioncraft . cli/output_path().","confidence":"exact","line":684,"expands":"sym:cargo visioncraft . cli/output_path()."}],"hash":"blake3:7a67d1cb03b3bb52a8fe9d0834e11961466acafa8c8c2ffb261312621ece5f52"},{"id":"sym:cargo visioncraft . cli/run().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/run().","span":{"start_line":759,"start_col":1,"end_line":915,"end_col":2},"sig_hash":"blake3-16:ba17c27738cfde5ad2571ad58ca94d50","body_hash":"blake3-16:08da835ef954e7dd9cc676a5efc8ef47","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . process/","sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft . evidence/ExecutionReceipt#"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":760},{"target":"sym:cargo visioncraft . cli/read_plan().","confidence":"exact","line":761},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":768},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":772},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":777,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":780,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":781,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":783},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":790,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":790},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":791},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":792},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":796},{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":797},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":798,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":799},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":799,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/evidence_parent().","confidence":"exact","line":801,"expands":"sym:cargo visioncraft . cli/evidence_parent()."},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":801,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":806,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":807,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":809},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":814,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":817},{"target":"sym:cargo visioncraft . cli/executable().","confidence":"exact","line":818},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":823},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":830},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":831},{"target":"sym:cargo visioncraft . process/run_command().","confidence":"exact","line":837},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":841},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":841},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":845},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":845},{"target":"sym:cargo visioncraft . cli/process_status().","confidence":"exact","line":847},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":853,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . plan/QualityPlan#digest().","confidence":"inferred","line":872},{"target":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","confidence":"exact","line":896,"expands":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":898},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":898,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/execution_exit().","confidence":"exact","line":899},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":911}],"hash":"blake3:f85f4c799e989e52e1d019de0ab972275cb43e5195f141cb2ea2d324af9bb903"},{"id":"sym:cargo visioncraft . cli/load_receipts().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/load_receipts().","span":{"start_line":917,"start_col":1,"end_line":947,"end_col":2},"sig_hash":"blake3-16:c5944f1ef230b917228e3114fc3f9133","body_hash":"blake3-16:8e82d035d63b0fd789327e31b5b9794c","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft . evidence/ExecutionReceipt#"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":921},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":928},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":933,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":940},{"target":"sym:cargo visioncraft . evidence/ExecutionReceipt#parse().","confidence":"exact","line":940},{"target":"sym:cargo visioncraft . cli/receipt_artifacts().","confidence":"exact","line":941},{"target":"sym:cargo visioncraft . cli/add_artifact().","confidence":"exact","line":942,"expands":"sym:cargo visioncraft . cli/add_artifact()."}],"hash":"blake3:cc786ac0e563e162c5bd861f9c216fe9ef10f557e6eeb37a0b004e691b4aa023"},{"id":"sym:cargo visioncraft . cli/evaluate_options().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/evaluate_options().","span":{"start_line":949,"start_col":1,"end_line":1094,"end_col":2},"sig_hash":"blake3-16:e24a4e8e44d00858f88e500a666ef939","body_hash":"blake3-16:9fd6438f6c66bc74969f7f025e4aabb5","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . plan/Subject#","sym:cargo visioncraft . evidence/VerifiedArtifacts#","sym:cargo visioncraft . cli/ContextFile#","sym:cargo visioncraft . evaluate/EvaluationContext#","sym:extern sealmap_corpus","sym:cargo visioncraft . evaluate/","sym:extern serde_json"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":950},{"target":"sym:cargo visioncraft . cli/read_plan().","confidence":"exact","line":951},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":954,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":955,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":958},{"target":"sym:cargo visioncraft . cli/selected_dirty().","confidence":"exact","line":963,"expands":"sym:cargo visioncraft . cli/selected_dirty()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":967},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":967},{"target":"sym:cargo visioncraft . cli/read_explicit().","confidence":"exact","line":973,"expands":"sym:cargo visioncraft . cli/read_explicit()."},{"target":"sym:cargo visioncraft . from_json().","confidence":"exact","line":974},{"target":"sym:cargo visioncraft . plan/Subject#validate().","confidence":"exact","line":975,"expands":"sym:cargo visioncraft . plan/Subject#validate()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":980},{"target":"sym:cargo visioncraft . evidence/VerifiedArtifacts#default().","confidence":"inferred","line":991},{"target":"sym:cargo visioncraft . cli/load_receipts().","confidence":"exact","line":994,"expands":"sym:cargo visioncraft . cli/load_receipts()."},{"target":"sym:cargo visioncraft . cli/ContextFile#default().","confidence":"inferred","line":996},{"target":"sym:cargo visioncraft . cli/read_explicit().","confidence":"exact","line":998,"expands":"sym:cargo visioncraft . cli/read_explicit()."},{"target":"sym:cargo visioncraft . from_json().","confidence":"exact","line":999},{"target":"sym:cargo visioncraft . cli/add_artifact().","confidence":"exact","line":1006,"expands":"sym:cargo visioncraft . cli/add_artifact()."},{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":1011,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . evaluate/EvaluationContext#new().","confidence":"exact","line":1026},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":1033},{"target":"sym:extern sealmap_corpus::route::Family::named","confidence":"external","line":1039},{"target":"sym:cargo visioncraft . evaluate/","confidence":"exact","line":1043},{"target":"sym:extern serde_json::to_value","confidence":"external","line":1050},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":1057}],"hash":"blake3:17642162233672dd735dae4ee72a7a222c770a69d34827a8c3af548eac157f76"},{"id":"sym:cargo visioncraft . cli/execute().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/execute().","span":{"start_line":1096,"start_col":1,"end_line":1135,"end_col":2},"sig_hash":"blake3-16:46912e87ff2e1ea76267f5fc634b601d","body_hash":"blake3-16:38f8733b2f66f86957663943eeb3898d","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft . deepsec/"],"calls":[{"target":"sym:cargo visioncraft . cli/init().","confidence":"exact","line":1105,"expands":"sym:cargo visioncraft . cli/init()."},{"target":"sym:cargo visioncraft . cli/read_plan().","confidence":"exact","line":1109},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":1111},{"target":"sym:cargo visioncraft . cli/run().","confidence":"exact","line":1123,"expands":"sym:cargo visioncraft . cli/run()."},{"target":"sym:cargo visioncraft . cli/evaluate_options().","confidence":"exact","line":1130,"expands":"sym:cargo visioncraft . cli/evaluate_options()."},{"target":"sym:cargo visioncraft . deepsec/execute().","confidence":"exact","line":1132,"expands":"sym:cargo visioncraft . deepsec/execute()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":1132}],"hash":"blake3:b33cd48ba99d0f8f35cf65973f7f754430fcf32c4df4237059c40674dbd2c4ce"}]},{"source":"src/deepsec.rs","document":"src/deepsec.rs.md","module":"sym:cargo visioncraft . deepsec/","source_hash":"blake3:f6a856414c586500e5bbcb69b8f4cee3caf40b2de0b8895792ad0ca34e45c977","document_hash":"blake3:ec097a9ceb33b6c3d8ac060a9854d8d96d05148616c6fb10a562fc98639c5423","fragments":[{"id":"structure:src/deepsec.rs","kind":"structure","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/","span":{"start_line":1,"start_col":1,"end_line":1063,"end_col":1},"sig_hash":"blake3-16:dfca6b22e7a0f75576ee19430ce800ad","body_hash":"blake3-16:cd635cb8681ff032b09a653c3982a09e","participants":["sym:cargo visioncraft . deepsec/","sym:cargo visioncraft . deepsec/Attempt#","sym:cargo visioncraft . deepsec/DeepsecOptions#","sym:cargo visioncraft . deepsec/DeepsecPolicy#","sym:cargo visioncraft . deepsec/GateError#","sym:cargo visioncraft . deepsec/StrictJson#"],"hash":"blake3:6eecc34c285fec9c493ea0145ea40bfa7badb172c994b1257ff76b6d5cbb9329"},{"id":"sym:cargo visioncraft . deepsec/DeepsecPolicy#validate().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/DeepsecPolicy#validate().","span":{"start_line":142,"start_col":5,"end_line":229,"end_col":6},"sig_hash":"blake3-16:8e9590b4e5ea930dbb967d625e57fb57","body_hash":"blake3-16:0aaf1b920c2175079b0541e62429279d","participants":["sym:cargo visioncraft . deepsec/DeepsecPolicy#","sym:cargo visioncraft . deepsec/","sym:extern url"],"calls":[{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":146},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":149},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":152},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":155},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":161},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":167},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":180},{"target":"sym:extern url::Url::parse","confidence":"external","line":183},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":184},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":192},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":200},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":206},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":216},{"target":"sym:cargo visioncraft . deepsec/duration_ms().","confidence":"exact","line":223},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":224}],"hash":"blake3:abe7fa45bd5abad24561011927a3cf90fe983f66bed974955fbc0f150c2a401a"},{"id":"sym:cargo visioncraft . deepsec/findings().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/findings().","span":{"start_line":371,"start_col":1,"end_line":410,"end_col":2},"sig_hash":"blake3-16:d958a149d303f700360dacf89d848981","body_hash":"blake3-16:d23d0fceb0331f95373edce172a94932","participants":["sym:cargo visioncraft . deepsec/","sym:extern serde_json"],"calls":[{"target":"sym:extern serde_json::from_slice","confidence":"external","line":372},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":373},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":378},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":388},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":395},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":402},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":405}],"hash":"blake3:730cdc58cc3f43348c0dce498d29c1d82277e0e08fec90504dd8015cc12953c5"},{"id":"sym:cargo visioncraft . deepsec/Attempt#command().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/Attempt#command().","span":{"start_line":484,"start_col":5,"end_line":559,"end_col":6},"sig_hash":"blake3-16:e8c318eaf968b6ab917a2c6d444e8f2e","body_hash":"blake3-16:4aa6ec82fcec8f10bf66efbf85f15248","participants":["sym:cargo visioncraft . deepsec/Attempt#","sym:cargo visioncraft . deepsec/","sym:cargo visioncraft . process/","sym:cargo visioncraft . git_metadata/","sym:extern serde_json"],"calls":[{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":497},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":500},{"target":"sym:cargo visioncraft . git_metadata/prefix().","confidence":"exact","line":502},{"target":"sym:cargo visioncraft . git_metadata/fixed_environment().","confidence":"exact","line":507},{"target":"sym:cargo visioncraft . deepsec/environment().","confidence":"exact","line":510},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":522},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":523},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":520},{"target":"sym:cargo visioncraft . process/run_command_with_env().","confidence":"exact","line":525,"expands":"sym:cargo visioncraft . process/run_command_with_env()."},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":527},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":528},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":539},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":540},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":537},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":545},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":548},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":549},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":553},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":557}],"hash":"blake3:217704a889e0dea86a0b3a481dc04ae14029e0b4c6895a34f03be84c965d8db4"},{"id":"sym:cargo visioncraft . deepsec/execute().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/execute().","span":{"start_line":618,"start_col":1,"end_line":1025,"end_col":2},"sig_hash":"blake3-16:0ba905b365d196f55d4ed680e35ea604","body_hash":"blake3-16:a139be56c5a4af8b6e650f9352bf23f8","participants":["sym:cargo visioncraft . deepsec/","sym:cargo visioncraft .","sym:cargo visioncraft . deepsec/DeepsecPolicy#","sym:extern serde_json","sym:cargo visioncraft . process/","sym:extern tempfile","sym:cargo visioncraft . deepsec/Attempt#","sym:extern recorded"],"calls":[{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":635},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":640},{"target":"sym:cargo visioncraft . from_json().","confidence":"exact","line":645},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":646},{"target":"sym:cargo visioncraft . deepsec/DeepsecPolicy#[Default]default().","confidence":"exact","line":647},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":666},{"target":"sym:cargo visioncraft . deepsec/root_for().","confidence":"exact","line":671},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":679},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":680},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":681},{"target":"sym:extern serde_json::to_string_pretty","confidence":"external","line":742},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":743},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":751},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":758},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":760},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":762},{"target":"sym:cargo visioncraft . deepsec/workspace_lock().","confidence":"exact","line":766},{"target":"sym:cargo visioncraft . deepsec/validate_workspace_tree().","confidence":"exact","line":767},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":769},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":771},{"target":"sym:cargo visioncraft . process/private_file().","confidence":"exact","line":772},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":775},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":776},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":773},{"target":"sym:extern tempfile::NamedTempFile::new_in","confidence":"external","line":778},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":782},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":785},{"target":"sym:extern serde_json::to_string_pretty","confidence":"external","line":791},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":792},{"target":"sym:extern tempfile::NamedTempFile::new_in","confidence":"external","line":794},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":799},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":812,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/supported_version().","confidence":"exact","line":832},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":833},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":838,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":849,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:extern recorded::select","confidence":"external","line":860},{"target":"sym:extern recorded::snapshot","confidence":"external","line":861},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":864},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":865},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":862},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":868},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":895,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":897},{"target":"sym:extern recorded::pending","confidence":"external","line":906},{"target":"sym:extern recorded::run_files","confidence":"external","line":910},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":927,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":929},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":932},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":935},{"target":"sym:extern recorded::snapshot","confidence":"external","line":940},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":943},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":944},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":941},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":947},{"target":"sym:extern recorded::validate_review","confidence":"external","line":949},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":969,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":971},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":973},{"target":"sym:cargo visioncraft . deepsec/findings().","confidence":"exact","line":974,"expands":"sym:cargo visioncraft . deepsec/findings()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":976},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":1015},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":1016},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":1013},{"target":"sym:extern serde_json::to_string_pretty","confidence":"external","line":1020},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":1021}],"hash":"blake3:e9b4f12a5bac11d760ae501ea05d3f3c81a0b569e93bdae46dd99b6f02ab5b2d"}]},{"source":"src/deepsec_evidence.rs","document":"src/deepsec_evidence.rs.md","module":"sym:cargo visioncraft . deepsec_evidence/","source_hash":"blake3:f26a627cb792b2b78f7637d38ad80a0e0260b566505bedf92cd524d64dd5a0ac","document_hash":"blake3:c9746c40e975c666b5eb5fb7d23018c83c87b179a6d625a52ef3903f5ec8ccb8","fragments":[{"id":"structure:src/deepsec_evidence.rs","kind":"structure","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/","span":{"start_line":1,"start_col":1,"end_line":317,"end_col":1},"sig_hash":"blake3-16:d29639f733f43b721a769946fd5c16ea","body_hash":"blake3-16:5c6b431f7b9b75878e334ded4e0529f8","participants":["sym:cargo visioncraft . deepsec_evidence/"],"hash":"blake3:2b62a4deed164da5864a4a3b4a5e4bcd5cf0545d80b644f32199c4c096571d9d"},{"id":"sym:cargo visioncraft . deepsec_evidence/confined().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/confined().","span":{"start_line":15,"start_col":1,"end_line":37,"end_col":2},"sig_hash":"blake3-16:339a3f31cc29d571f0d49cac65efa8cf","body_hash":"blake3-16:bfc51a62ae369d14245e4fe1e398ad60","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:cargo visioncraft .","sym:extern visioncraft"],"calls":[{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":16},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":20},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":29},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":33}],"hash":"blake3:b8c9c4216ed7327069ac7d1d1e50af8df2c6387d1660f7931168280d9a740822"},{"id":"sym:cargo visioncraft . deepsec_evidence/snapshot().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/snapshot().","span":{"start_line":38,"start_col":1,"end_line":60,"end_col":2},"sig_hash":"blake3-16:f9fca86ed05e6dea51f36aa77af98298","body_hash":"blake3-16:92e1f22220e61aed17b21bca7709b198","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft","sym:cargo visioncraft ."],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":40},{"target":"sym:cargo visioncraft . deepsec_evidence/confined().","confidence":"exact","line":46,"expands":"sym:cargo visioncraft . deepsec_evidence/confined()."},{"target":"sym:extern visioncraft::read_bounded","confidence":"inferred","line":46},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":49},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":56}],"hash":"blake3:5653bc15ccdd69ddf29a8b3373e42cc5d25cac283259f0cef32cb2a6d5713278"},{"id":"sym:cargo visioncraft . deepsec_evidence/select().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/select().","span":{"start_line":61,"start_col":1,"end_line":169,"end_col":2},"sig_hash":"blake3-16:cc9a89e8f0905b3cb12ddfe8572273b4","body_hash":"blake3-16:a235aab603da0aabd165ee2efd5dc868","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft"],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":71},{"target":"sym:extern visioncraft::read_bounded","confidence":"inferred","line":75},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":103},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":111},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":126},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":132},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":140},{"target":"sym:cargo visioncraft . deepsec_evidence/confined().","confidence":"exact","line":146,"expands":"sym:cargo visioncraft . deepsec_evidence/confined()."},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":160},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":162}],"hash":"blake3:5bb9a75aa00caea45c6e4b56b2814cf5c9c73123ebbc47fc505690ae8c94d101"},{"id":"sym:cargo visioncraft . deepsec_evidence/run_files().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/run_files().","span":{"start_line":170,"start_col":1,"end_line":193,"end_col":2},"sig_hash":"blake3-16:6da82f7f40f25f96425a127fb162af24","body_hash":"blake3-16:f7cb0af119c19b3933742680610ae1da","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft"],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":176},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":178},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":181},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":182},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":184}],"hash":"blake3:1624786ac1edaf9933c59e02458c9e8a45069628a872c991e089a8730adc656e"},{"id":"sym:cargo visioncraft . deepsec_evidence/validate_review().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/validate_review().","span":{"start_line":220,"start_col":1,"end_line":317,"end_col":2},"sig_hash":"blake3-16:48c209a2019e0cdfb19ce0ddd22d8346","body_hash":"blake3-16:bdc3f563f8b939e53ba3780bfde17d48","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern sealmap_corpus","sym:extern serde_json","sym:extern visioncraft","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . deepsec_evidence/run_files().","confidence":"exact","line":229,"expands":"sym:cargo visioncraft . deepsec_evidence/run_files()."},{"target":"sym:cargo visioncraft . deepsec_evidence/object().","confidence":"exact","line":230},{"target":"sym:extern sealmap_corpus::review::Artifact::iter","confidence":"external","line":236},{"target":"sym:cargo visioncraft . deepsec_evidence/file_record().","confidence":"exact","line":240},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":247},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":248},{"target":"sym:extern visioncraft::write_new","confidence":"inferred","line":249},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":251},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":256},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":257},{"target":"sym:extern sealmap_corpus::review::Artifact::len","confidence":"external","line":262},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":264},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":276},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":283},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":286},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":297},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":308}],"hash":"blake3:ae2141692794b47fd4e101b62646dbe9a0868370fb4b96e96f8a8df88584ea13"}]},{"source":"src/evaluate.rs","document":"src/evaluate.rs.md","module":"sym:cargo visioncraft . evaluate/","source_hash":"blake3:68c30067ced8712ddcf6cb6c32ff742f62c952f39d3d4fa57951fe599b7da94c","document_hash":"blake3:aec7081440aea0a482049a8ca67278c55d75fae2f7815adcbc1faa6b97987d87","fragments":[{"id":"structure:src/evaluate.rs","kind":"structure","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/","span":{"start_line":1,"start_col":1,"end_line":657,"end_col":1},"sig_hash":"blake3-16:9fe9b147ca2d959744dccbc9bb23ac64","body_hash":"blake3-16:6fe55723dc753cb595c465a48957545a","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft . evaluate/CheckOutcome#","sym:cargo visioncraft . evaluate/CheckReport#","sym:cargo visioncraft . evaluate/EvaluationContext#","sym:cargo visioncraft . evaluate/ExpectationReport#","sym:cargo visioncraft . evaluate/GateOutcome#","sym:cargo visioncraft . evaluate/GateReport#"],"hash":"blake3:d5091dfff7bb58c6eb3e49cacb4b5589dcaf0e603efe16f2f4b6f4f74c0df81b"},{"id":"sym:cargo visioncraft . evaluate/check_receipt().","kind":"sequence","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/check_receipt().","span":{"start_line":160,"start_col":1,"end_line":273,"end_col":2},"sig_hash":"blake3-16:ee70d752233f4499288b800fcec0a414","body_hash":"blake3-16:d1fb01a0dcd74e443f9c5104f4378bc0","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft . evidence/ExecutionReceipt#","sym:cargo visioncraft . plan/","sym:cargo visioncraft . evidence/VerifiedArtifacts#"],"calls":[{"target":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","confidence":"exact","line":168,"expands":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate()."},{"target":"sym:cargo visioncraft . plan/same_inputs().","confidence":"exact","line":177},{"target":"sym:cargo visioncraft . evaluate/context_limits().","confidence":"exact","line":183},{"target":"sym:cargo visioncraft . evaluate/age_limit().","confidence":"exact","line":184},{"target":"sym:cargo visioncraft . evidence/VerifiedArtifacts#byte_len().","confidence":"inferred","line":211}],"hash":"blake3:03deb8052d7f7256279b5dd683bac32c7d37e95026d1630b4e041a7b51e85f0e"},{"id":"sym:cargo visioncraft . evaluate/assessment_binding().","kind":"sequence","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/assessment_binding().","span":{"start_line":298,"start_col":1,"end_line":320,"end_col":2},"sig_hash":"blake3-16:e2d6db985ebd381da5d83e24ce107563","body_hash":"blake3-16:7b52282e846da93f2cde20af7045a03b","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":307},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":311},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":312},{"target":"sym:cargo visioncraft . evaluate/age_limit().","confidence":"exact","line":317},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":316}],"hash":"blake3:30162b56ccfa772885e62b9a777b4781fbd01a3957b7eb431ef2feb04c8d50e9"},{"id":"sym:cargo visioncraft . evaluate/expectation_report().","kind":"sequence","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/expectation_report().","span":{"start_line":322,"start_col":1,"end_line":524,"end_col":2},"sig_hash":"blake3-16:60bd522cd3ba06f3d9da1f7b3e90b52b","body_hash":"blake3-16:e4d1797b13f584d6f345f1601b1187e9","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft .","sym:extern sealmap_corpus"],"calls":[{"target":"sym:cargo visioncraft . evaluate/referenced_check().","confidence":"exact","line":333},{"target":"sym:cargo visioncraft . evaluate/referenced_check().","confidence":"exact","line":336},{"target":"sym:cargo visioncraft . evaluate/referenced_check().","confidence":"exact","line":339},{"target":"sym:cargo visioncraft . evaluate/assessment_binding().","confidence":"exact","line":371,"expands":"sym:cargo visioncraft . evaluate/assessment_binding()."},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":381},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":382},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":383},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":380},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":386},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":391},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":400},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":404},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":411},{"target":"sym:extern sealmap_corpus::route::cross_family_with","confidence":"external","line":421},{"target":"sym:cargo visioncraft . evaluate/assessment_binding().","confidence":"exact","line":479,"expands":"sym:cargo visioncraft . evaluate/assessment_binding()."},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":490},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":490},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":489}],"hash":"blake3:621bb154f0bc58def0d9b99839bfb5f7f07500da87de83f718956d20bb7d43f5"}]},{"source":"src/evidence.rs","document":"src/evidence.rs.md","module":"sym:cargo visioncraft . evidence/","source_hash":"blake3:edfe990a885f2bcad685855fe0c87e11878174d676e4414f4f9448e818ca520a","document_hash":"blake3:92db7d2db5b346b252f2fd1d9472793cfc0dda06b4ac5f891e0e98a8629fc804","fragments":[{"id":"structure:src/evidence.rs","kind":"structure","document":"src/evidence.rs.md","symbol":"sym:cargo visioncraft . evidence/","span":{"start_line":1,"start_col":1,"end_line":292,"end_col":1},"sig_hash":"blake3-16:af11808614b221a0d9791b5c9c0aa422","body_hash":"blake3-16:07ca5c0150b9e722b1428c85557ebe66","participants":["sym:cargo visioncraft . evidence/","sym:cargo visioncraft . evidence/Actor#","sym:cargo visioncraft . evidence/AuditReceipt#","sym:cargo visioncraft . evidence/AuditVerdict#","sym:cargo visioncraft . evidence/ExecutionReceipt#","sym:cargo visioncraft . evidence/ManualObservation#","sym:cargo visioncraft . evidence/ProcessStatus#","sym:cargo visioncraft . evidence/ReportedResult#","sym:cargo visioncraft . evidence/VerifiedArtifacts#"],"hash":"blake3:4cac75df033fe3d821a9d0b2c1862cba2880e53086a68efdbae14c83e5830ef8"},{"id":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","kind":"sequence","document":"src/evidence.rs.md","symbol":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","span":{"start_line":107,"start_col":5,"end_line":178,"end_col":6},"sig_hash":"blake3-16:ba67f81a1ab12cfa2f20da686b32f5f9","body_hash":"blake3-16:85e6fc9a46be325577dbc0b80d49e394","participants":["sym:cargo visioncraft . evidence/ExecutionReceipt#","sym:cargo visioncraft .","sym:cargo visioncraft . plan/Subject#","sym:cargo visioncraft . plan/Invocation#","sym:cargo visioncraft . plan/"],"calls":[{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":113},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":115},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":115},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":114},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":118},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":118},{"target":"sym:cargo visioncraft . plan/Subject#validate().","confidence":"exact","line":119,"expands":"sym:cargo visioncraft . plan/Subject#validate()."},{"target":"sym:cargo visioncraft . plan/Invocation#validate().","confidence":"exact","line":120,"expands":"sym:cargo visioncraft . plan/Invocation#validate()."},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":122},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":121},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":126},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":126},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":129},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":129},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":131},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":135},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":140},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":144},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":149},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":155},{"target":"sym:cargo visioncraft . plan/validate_input_paths().","confidence":"exact","line":157},{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":161},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":160},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":167},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":166},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":172},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":172},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":171},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":175}],"hash":"blake3:5d5543a5441c2972246e77d27188c7df4e53e2c8f859470ae0c0453e4c16b416"}]},{"source":"src/git_metadata.rs","document":"src/git_metadata.rs.md","module":"sym:cargo visioncraft . git_metadata/","source_hash":"blake3:36f06c2d0b9d416dc106fd7d20839a5fc424fa52dc1e40f572a1acb24050a467","document_hash":"blake3:46ca7ecba1f564098b57d4959fc54fd9ba85ae570aa82e50f7a56a58fc15da66","fragments":[{"id":"structure:src/git_metadata.rs","kind":"structure","document":"src/git_metadata.rs.md","symbol":"sym:cargo visioncraft . git_metadata/","span":{"start_line":1,"start_col":1,"end_line":30,"end_col":1},"sig_hash":"blake3-16:c95500707a557a0575618bc2539225f2","body_hash":"blake3-16:f31363b4d21a99321ffe2494091f132f","participants":["sym:cargo visioncraft . git_metadata/"],"hash":"blake3:80a57b7bae6a450ff5c782a4d5b03d35b571a7e7dfa2d7c7a9266be730c4f555"}]},{"source":"src/lib.rs","document":"src/lib.rs.md","module":"sym:cargo visioncraft .","source_hash":"blake3:bd0cbb39c4723d919330852c9a157a2284d5b8102817d2c74eb7dd89a715bffb","document_hash":"blake3:a2cf789c4c08e0dc3d6f4a053570d75dc8cfd0cb2d49021eeec4364ad51fa0e3","fragments":[{"id":"structure:src/lib.rs","kind":"structure","document":"src/lib.rs.md","symbol":"sym:cargo visioncraft .","span":{"start_line":1,"start_col":1,"end_line":132,"end_col":1},"sig_hash":"blake3-16:ef5f0989f89148798c9d4374da243656","body_hash":"blake3-16:07498bcaf3ef330f07f8945432f31636","participants":["sym:cargo visioncraft .","sym:cargo visioncraft . ContractError#"],"hash":"blake3:9f5d5b04a6ee671ff43fa2cda20f9bd1e2116468c93c310aafc175d99a64ccc4"}]},{"source":"src/main.rs","document":"src/main.rs.md","module":"sym:cargo visioncraft_main .","source_hash":"blake3:4bb59bf863aec89c7e0f6ea0dc232c477e58b0d54775b003a29d43b892e22326","document_hash":"blake3:74400fa28d70e441bfb8d12dd9804989463f276c65f910faed90e827f7563fb8","fragments":[{"id":"structure:src/main.rs","kind":"structure","document":"src/main.rs.md","symbol":"sym:cargo visioncraft_main .","span":{"start_line":1,"start_col":1,"end_line":39,"end_col":1},"sig_hash":"blake3-16:be7e0aa42067d3874629adeff2b5a523","body_hash":"blake3-16:fc2e76f655eeaf6fb63b94d01fdf8e29","participants":["sym:cargo visioncraft_main ."],"hash":"blake3:6072a92081ad96885a435ab18fa15f7156552c9f5a91ffd3b893d30664f7c127"}]},{"source":"src/plan.rs","document":"src/plan.rs.md","module":"sym:cargo visioncraft . plan/","source_hash":"blake3:a0eaf6b6e34139a3b02ddc3d521d69dc4c064884b96dfe85585b1a1e7da2107d","document_hash":"blake3:52a11da34333ac5b351ee8aecb9f323047782e5c9a5a9c3d35b3707c159fa8f8","fragments":[{"id":"structure:src/plan.rs","kind":"structure","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/","span":{"start_line":1,"start_col":1,"end_line":413,"end_col":1},"sig_hash":"blake3-16:a24f0f42e161b5767c66583d880ff1c1","body_hash":"blake3-16:244666ed06402316b2c9d9f1e3d97726","participants":["sym:cargo visioncraft . plan/","sym:cargo visioncraft . plan/CheckSpec#","sym:cargo visioncraft . plan/Evaluator#","sym:cargo visioncraft . plan/EvidenceCategory#","sym:cargo visioncraft . plan/Expectation#","sym:cargo visioncraft . plan/GatePolicy#","sym:cargo visioncraft . plan/Invocation#","sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft . plan/Stabilizer#","sym:cargo visioncraft . plan/Subject#"],"hash":"blake3:c3b2d48210fcb0809c8dffe5957419f886988159fb60f056c51dd599ada41860"},{"id":"sym:cargo visioncraft . plan/Subject#validate().","kind":"sequence","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/Subject#validate().","span":{"start_line":36,"start_col":5,"end_line":58,"end_col":6},"sig_hash":"blake3-16:cc5a01905f372f11d7204d0e8ae9b415","body_hash":"blake3-16:5c8417ac75b7f4969f36b4094d1bba88","participants":["sym:cargo visioncraft . plan/Subject#","sym:cargo visioncraft .","sym:cargo visioncraft . plan/"],"calls":[{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":41},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":41},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":43},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":42},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":47},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":46},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":50},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":55},{"target":"sym:cargo visioncraft . plan/validate_inputs().","confidence":"exact","line":57}],"hash":"blake3:322d9507a0187eaa308b3d532d47b123850c5a0d98d5ae483d9298c64ffe0ff3"},{"id":"sym:cargo visioncraft . plan/Invocation#validate().","kind":"sequence","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/Invocation#validate().","span":{"start_line":104,"start_col":5,"end_line":137,"end_col":6},"sig_hash":"blake3-16:df6aee1d4a2a9d4b92536e69433d3c6a","body_hash":"blake3-16:49668b9727c1ac54be4cd4c716e96fee","participants":["sym:cargo visioncraft . plan/Invocation#","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":109},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":109},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":110},{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":115},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":114},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":120},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":127},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":129},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":133}],"hash":"blake3:3354fc277d9bd09a45bbea06e5bc7342f7c586064f59d475a64b2bf33d0fda57"},{"id":"sym:cargo visioncraft . plan/QualityPlan#validate().","kind":"sequence","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/QualityPlan#validate().","span":{"start_line":291,"start_col":5,"end_line":398,"end_col":6},"sig_hash":"blake3-16:fa4cb29f8ee4f18407e9aa68bcbe8d75","body_hash":"blake3-16:16e4b5b86916c3ea0a2107386a4cc734","participants":["sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft .","sym:cargo visioncraft . plan/Subject#"],"calls":[{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":296},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":297},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":301},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":301},{"target":"sym:cargo visioncraft . plan/Subject#validate().","confidence":"exact","line":302,"expands":"sym:cargo visioncraft . plan/Subject#validate()."},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":303},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":307},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":317},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":316},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":327},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":331},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":335},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":338},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":346},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":354},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":353},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":362},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":361},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":365},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":365},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":367},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":374},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":380},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":379},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":385},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":391}],"hash":"blake3:a69180a482bd092c9035df0f4320ba289ec9d3162ec8ec2442e80c95752b5e56"}]},{"source":"src/process.rs","document":"src/process.rs.md","module":"sym:cargo visioncraft . process/","source_hash":"blake3:aba99dafa4cb40a2a286eaa16908067cf850cba5953360fec3b16569bfff0d28","document_hash":"blake3:ea889a787c6d96c8556deb1e8b85275600fd3920439168157dbb0b41aded78fa","fragments":[{"id":"structure:src/process.rs","kind":"structure","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/","span":{"start_line":1,"start_col":1,"end_line":727,"end_col":1},"sig_hash":"blake3-16:7e2098952f191664fce2401b4fe2c94b","body_hash":"blake3-16:613e44753e01981ef23d4559ae0ecf20","participants":["sym:cargo visioncraft . process/","sym:cargo visioncraft . process/CapturedRun#","sym:cargo visioncraft . process/Termination#","sym:cargo visioncraft . process/linux_proc/"],"hash":"blake3:16d6e3cdcb6791ae483d161c57a6207500a8f8ee76e3321bb2e9ed2fb52fdaab"},{"id":"sym:cargo visioncraft . process/group_running().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/group_running().","span":{"start_line":205,"start_col":1,"end_line":227,"end_col":2},"sig_hash":"blake3-16:450aa867c587af8c528981007e87506e","body_hash":"blake3-16:55cd57e12ea1170ff028ca7b1deaf230","participants":["sym:cargo visioncraft . process/","sym:extern nix","sym:cargo visioncraft . process/linux_proc/"],"calls":[{"target":"sym:extern nix::unistd::Pid::from_raw","confidence":"external","line":213},{"target":"sym:extern nix::sys::signal::killpg","confidence":"external","line":213},{"target":"sym:cargo visioncraft . process/group_probe().","confidence":"exact","line":213},{"target":"sym:cargo visioncraft . process/linux_proc/group_running().","confidence":"exact","line":219,"expands":"sym:cargo visioncraft . process/linux_proc/group_running()."}],"hash":"blake3:160b1938d01776868bd9ac1e251b2293252b7cbbffe4840e44f74fc947cbcc8b"},{"id":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","span":{"start_line":330,"start_col":5,"end_line":338,"end_col":6},"sig_hash":"blake3-16:49458981d13cf9ce4c6c0a96ca26feec","body_hash":"blake3-16:f2879a39f584e155dc13e267a52ae2ef","participants":["sym:cargo visioncraft . process/linux_proc/","sym:extern nix","sym:extern io"],"calls":[{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":332},{"target":"sym:extern nix::unistd::Pid::from_raw","confidence":"external","line":331},{"target":"sym:extern nix::unistd::getpgid","confidence":"external","line":331},{"target":"sym:extern io::Error::from","confidence":"external","line":336}],"hash":"blake3:a798cd074970aad872574e1501ad3536ce7cd6d6435fcfd5a05010cc94c05bd3"},{"id":"sym:cargo visioncraft . process/linux_proc/tasks_dead().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/linux_proc/tasks_dead().","span":{"start_line":340,"start_col":5,"end_line":360,"end_col":6},"sig_hash":"blake3-16:a9f9ab596bca87189a028b260242a28e","body_hash":"blake3-16:123a9041f4c2fbded78b9b11120156c3","participants":["sym:cargo visioncraft . process/linux_proc/"],"calls":[{"target":"sym:cargo visioncraft . process/linux_proc/ids().","confidence":"exact","line":341},{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":343},{"target":"sym:cargo visioncraft . process/linux_proc/bounded_read().","confidence":"exact","line":346},{"target":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","confidence":"exact","line":349,"expands":"sym:cargo visioncraft . process/linux_proc/no_longer_member()."},{"target":"sym:cargo visioncraft . process/linux_proc/state().","confidence":"exact","line":355},{"target":"sym:cargo visioncraft . process/linux_proc/dead().","confidence":"exact","line":355}],"hash":"blake3:d005e864bcd330ec387e43270ff69774f1c4919c5f6b84ab27bcd66989a7fc36"},{"id":"sym:cargo visioncraft . process/linux_proc/dead_members().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/linux_proc/dead_members().","span":{"start_line":362,"start_col":5,"end_line":396,"end_col":6},"sig_hash":"blake3-16:3b267a99719de21556fd8c379c12f9cc","body_hash":"blake3-16:f9cf83781959814ebc4fb431277ff7bf","participants":["sym:cargo visioncraft . process/linux_proc/"],"calls":[{"target":"sym:cargo visioncraft . process/linux_proc/ids().","confidence":"exact","line":364},{"target":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","confidence":"exact","line":365,"expands":"sym:cargo visioncraft . process/linux_proc/no_longer_member()."},{"target":"sym:cargo visioncraft . process/linux_proc/bounded_read().","confidence":"exact","line":369},{"target":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","confidence":"exact","line":372,"expands":"sym:cargo visioncraft . process/linux_proc/no_longer_member()."},{"target":"sym:cargo visioncraft . process/linux_proc/state().","confidence":"exact","line":378},{"target":"sym:cargo visioncraft . process/linux_proc/dead().","confidence":"exact","line":378},{"target":"sym:cargo visioncraft . process/linux_proc/tasks_dead().","confidence":"exact","line":383,"expands":"sym:cargo visioncraft . process/linux_proc/tasks_dead()."},{"target":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","confidence":"exact","line":387,"expands":"sym:cargo visioncraft . process/linux_proc/no_longer_member()."}],"hash":"blake3:ee87f97968bf4f63ce23188e9b3e96ed180abb5ab2ad8c9f08b5b91944593512"},{"id":"sym:cargo visioncraft . process/linux_proc/group_running().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/linux_proc/group_running().","span":{"start_line":398,"start_col":5,"end_line":430,"end_col":6},"sig_hash":"blake3-16:99a2a0a6fb625ac643156e3927572fa6","body_hash":"blake3-16:66cd29c67e27972c551df4e13580259c","participants":["sym:cargo visioncraft . process/linux_proc/","sym:extern nix","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:cargo visioncraft . process/linux_proc/bounded_read().","confidence":"exact","line":399},{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":400},{"target":"sym:cargo visioncraft . process/linux_proc/unrestricted().","confidence":"exact","line":400},{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":401},{"target":"sym:cargo visioncraft . process/linux_proc/bounded_read().","confidence":"exact","line":405},{"target":"sym:cargo visioncraft . process/linux_proc/state().","confidence":"exact","line":404},{"target":"sym:cargo visioncraft . process/linux_proc/dead_members().","confidence":"exact","line":411,"expands":"sym:cargo visioncraft . process/linux_proc/dead_members()."},{"target":"sym:extern nix::unistd::Pid::from_raw","confidence":"external","line":415},{"target":"sym:extern nix::sys::signal::killpg","confidence":"external","line":415},{"target":"sym:cargo visioncraft . process/group_probe().","confidence":"exact","line":415},{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":417},{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":429}],"hash":"blake3:6f2204d56010527ea7f44aa5c8de7f0dc91868d5e56ecdf52bf420dae22da166"},{"id":"sym:cargo visioncraft . process/run_command_with_env().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/run_command_with_env().","span":{"start_line":518,"start_col":1,"end_line":727,"end_col":2},"sig_hash":"blake3-16:60939e55bba0ee305de92ce58430f493","body_hash":"blake3-16:dcb60b2486836c8f6dd48dcb488714b5","participants":["sym:cargo visioncraft . process/","sym:cargo visioncraft . plan/Invocation#"],"calls":[{"target":"sym:cargo visioncraft . plan/Invocation#validate().","confidence":"exact","line":545,"expands":"sym:cargo visioncraft . plan/Invocation#validate()."},{"target":"sym:cargo visioncraft . process/unix_now().","confidence":"exact","line":548},{"target":"sym:cargo visioncraft . process/private_file().","confidence":"exact","line":552},{"target":"sym:cargo visioncraft . process/private_file().","confidence":"exact","line":553},{"target":"sym:cargo visioncraft . process/unix_now().","confidence":"exact","line":605},{"target":"sym:cargo visioncraft . process/capture().","confidence":"exact","line":614},{"target":"sym:cargo visioncraft . process/capture().","confidence":"exact","line":622},{"target":"sym:cargo visioncraft . process/group_running().","confidence":"exact","line":655,"expands":"sym:cargo visioncraft . process/group_running()."},{"target":"sym:cargo visioncraft . process/signal_group().","confidence":"exact","line":686},{"target":"sym:cargo visioncraft . process/signal_group().","confidence":"exact","line":697},{"target":"sym:cargo visioncraft . process/unix_now().","confidence":"exact","line":723}],"hash":"blake3:27cdad6db51d3eabed0bdbdb4621a85aecb304f5ed2208335c67482e09f1168f"}]}]} +{"schema_version":2,"generator":"sealmap-corpus 0.4.0","codebase":"visioncraft","stats":{"files":10,"symbols":182,"relations":691,"flows":90,"calls":583},"documents":[{"source":"src/cli.rs","document":"src/cli.rs.md","module":"sym:cargo visioncraft . cli/","source_hash":"blake3:88c24a1ad87b7d1fdf86ccd6ec14585657147358a0f29d10bee5669885c5c451","document_hash":"blake3:0870c2dddd5e619052bfb99112561eeff45962a4862a14e3eead7cb93658c40a","fragments":[{"id":"structure:src/cli.rs","kind":"structure","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/","span":{"start_line":1,"start_col":1,"end_line":1118,"end_col":1},"sig_hash":"blake3-16:a91e60562b65dab9be5fcfdd480a0025","body_hash":"blake3-16:fa4fea206fa706e5f09f3fe486c6d8d9","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft . cli/Cli#","sym:cargo visioncraft . cli/CliError#","sym:cargo visioncraft . cli/ContextFile#","sym:cargo visioncraft . cli/EvaluateOptions#","sym:cargo visioncraft . cli/ExpectationCommand#","sym:cargo visioncraft . cli/FamilyDeclaration#","sym:cargo visioncraft . cli/GateCommand#","sym:cargo visioncraft . cli/GitOutput#","sym:cargo visioncraft . cli/InitOptions#","sym:cargo visioncraft . cli/Operation#","sym:cargo visioncraft . cli/PlanCommand#","sym:cargo visioncraft . cli/RunOptions#","sym:cargo visioncraft . cli/SnapshotInput#"],"hash":"blake3:cc028d12f950c3ae1e85c12d11800b79b52157876e4bc9dd1614e6a982724168"},{"id":"sym:cargo visioncraft . cli/confined().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/confined().","span":{"start_line":225,"start_col":1,"end_line":251,"end_col":2},"sig_hash":"blake3-16:0f062b609af0623484ee4a8f3ce0791c","body_hash":"blake3-16:4d6d3d8c0f03abdfbfa2e19fad43f067","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":229},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":230},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":235},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":240},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":248}],"hash":"blake3:10134bbd7624f9bdd4c0c962084ddf99406fd07aaff1c112d8e6fde98e6256d2"},{"id":"sym:cargo visioncraft . cli/read_explicit().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/read_explicit().","span":{"start_line":273,"start_col":1,"end_line":285,"end_col":2},"sig_hash":"blake3-16:0135480ca8cad65a15367671ed65406d","body_hash":"blake3-16:2795f0c0dbe9df2e76d5b564e531760e","participants":["sym:cargo visioncraft . cli/"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":274},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":282},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":283,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":284}],"hash":"blake3:ea44521ca2c9580a30bcd4324260bf263e6d214f80c0579223fe16ef7cab9f86"},{"id":"sym:cargo visioncraft . cli/output_path().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/output_path().","span":{"start_line":287,"start_col":1,"end_line":312,"end_col":2},"sig_hash":"blake3-16:dbdb74d9394b0d29e9e3e8e51c008181","body_hash":"blake3-16:ca6d64c44631f2c0ee6c2ac804186a41","participants":["sym:cargo visioncraft . cli/"],"calls":[{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":296},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":302},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":304},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":306},{"target":"sym:cargo visioncraft . cli/io_error().","confidence":"exact","line":308}],"hash":"blake3:16ae04e0f4143479ef97deccd15f1e0d6c9c12d1f16c3de82ed63430b15466ec"},{"id":"sym:cargo visioncraft . cli/write_new().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/write_new().","span":{"start_line":314,"start_col":1,"end_line":326,"end_col":2},"sig_hash":"blake3-16:2d4d3f36490d72b3f6dc2d027eca4f3e","body_hash":"blake3-16:697a3ac4de3c725a30cfdc25488b8f86","participants":["sym:cargo visioncraft . cli/","sym:extern tempfile"],"calls":[{"target":"sym:cargo visioncraft . cli/output_path().","confidence":"exact","line":315,"expands":"sym:cargo visioncraft . cli/output_path()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":318},{"target":"sym:extern tempfile::NamedTempFile::new_in","confidence":"external","line":319},{"target":"sym:cargo visioncraft . cli/io_error().","confidence":"exact","line":324}],"hash":"blake3:457d2ebe0c5c2371326d12fd034f42e6ec1b554309aa824f919c052357d114df"},{"id":"sym:cargo visioncraft . cli/git().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/git().","span":{"start_line":345,"start_col":1,"end_line":405,"end_col":2},"sig_hash":"blake3-16:4841aa17643eae3fb5fe09d3badd3661","body_hash":"blake3-16:f6010aec4da04480c3e910c072d027ab","participants":["sym:cargo visioncraft . cli/","sym:extern tempfile","sym:cargo visioncraft . git_metadata/","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:extern tempfile::Builder::new","confidence":"external","line":346},{"target":"sym:extern tempfile::Builder::prefix","confidence":"external","line":347},{"target":"sym:extern tempfile::Builder::permissions","confidence":"external","line":351},{"target":"sym:extern tempfile::Builder::tempdir","confidence":"external","line":353},{"target":"sym:cargo visioncraft . git_metadata/prefix().","confidence":"exact","line":359},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":364},{"target":"sym:cargo visioncraft . git_metadata/fixed_environment().","confidence":"exact","line":372},{"target":"sym:cargo visioncraft . process/run_command_with_env().","confidence":"exact","line":383,"expands":"sym:cargo visioncraft . process/run_command_with_env()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":395},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":397},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":398},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":399},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":400}],"hash":"blake3:83e03825a35a5889cc5fdc8f48f354c078f2c26ce2c1f5b2a27c57c91d69ef20"},{"id":"sym:cargo visioncraft . cli/revision().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/revision().","span":{"start_line":407,"start_col":1,"end_line":417,"end_col":2},"sig_hash":"blake3-16:0b6fb7f218212ea850ac236d821d8a54","body_hash":"blake3-16:57f70fb943003d553d789a8ac8afdf57","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":408,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":410},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":413},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":414}],"hash":"blake3:6a47990d6e52a53cd8a184d578ac35266d83543a99f35ac8eb40a6ae358444e3"},{"id":"sym:cargo visioncraft . cli/selected_dirty().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/selected_dirty().","span":{"start_line":419,"start_col":1,"end_line":467,"end_col":2},"sig_hash":"blake3-16:466ae4a23ec9651aa81d4bed047fce21","body_hash":"blake3-16:8294488859feb1584175cfb2e805623a","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft . git_metadata/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . git_metadata/tree_arguments().","confidence":"exact","line":422},{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":424,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":426},{"target":"sym:cargo visioncraft . git_metadata/tree_entries().","confidence":"exact","line":429},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":429},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":435},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":436},{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":438,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":440},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":443},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":447},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":449},{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":451,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":453},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":455},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":457,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":458},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":462}],"hash":"blake3:00f70b07970846caf1ec526211e7375fa75eccb9ff1f99f04f5e73430d8e941c"},{"id":"sym:cargo visioncraft . cli/inputs().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/inputs().","span":{"start_line":476,"start_col":1,"end_line":504,"end_col":2},"sig_hash":"blake3-16:ed0d5f7af2c90806f98bbe55046295b0","body_hash":"blake3-16:a4fe913978641a3fc470a6673895dbdd","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":479,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":482},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":482},{"target":"sym:cargo visioncraft . cli/io_error().","confidence":"exact","line":492},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":494}],"hash":"blake3:3f2dccdf84b13932d2d5f50d867c14fdcb3bccb66ede478c1abcba1fd56cc8a7"},{"id":"sym:cargo visioncraft . cli/source_snapshot().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/source_snapshot().","span":{"start_line":506,"start_col":1,"end_line":540,"end_col":2},"sig_hash":"blake3-16:99ceb13e4265b3151783ffc6a3e45c52","body_hash":"blake3-16:cbf9aee3425988e9536de14608e8da81","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:extern sealmap_corpus"],"calls":[{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":515,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":515},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":518},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":523},{"target":"sym:extern sealmap_corpus::review::Artifact::iter","confidence":"external","line":525},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":528},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":539}],"hash":"blake3:f3d87fe2bf48f895fb27ad21313f2b1c7930ba3db6156c76295df6bb381ab3a4"},{"id":"sym:cargo visioncraft . cli/init().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/init().","span":{"start_line":547,"start_col":1,"end_line":635,"end_col":2},"sig_hash":"blake3-16:b4e883cfce087fb3dfc81327eb4ad912","body_hash":"blake3-16:b5e11d29744c7e97abe293abd262f6ed","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":548},{"target":"sym:cargo visioncraft . cli/output_path().","confidence":"exact","line":549,"expands":"sym:cargo visioncraft . cli/output_path()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":553},{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":556},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":557},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":560,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":561,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/selected_dirty().","confidence":"exact","line":562,"expands":"sym:cargo visioncraft . cli/selected_dirty()."},{"target":"sym:cargo visioncraft . cli/source_snapshot().","confidence":"exact","line":564,"expands":"sym:cargo visioncraft . cli/source_snapshot()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":572},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":577},{"target":"sym:cargo visioncraft . plan/QualityPlan#validate().","confidence":"exact","line":617,"expands":"sym:cargo visioncraft . plan/QualityPlan#validate()."},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":618,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":619,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":620},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":623},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":625},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":626,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":628,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":630},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":630,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":631}],"hash":"blake3:2bd9ae15fbaff3cd2eec8f3f3539d22c3dd9870def20c2e0f278d9303ee76f01"},{"id":"sym:cargo visioncraft . cli/add_artifact().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/add_artifact().","span":{"start_line":637,"start_col":1,"end_line":645,"end_col":2},"sig_hash":"blake3-16:f0e71327596608de7e6b1f6a54853e2d","body_hash":"blake3-16:9b18aea04b32a8ac770134c2c7b25309","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . evidence/VerifiedArtifacts#"],"calls":[{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":642},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":643,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":643},{"target":"sym:cargo visioncraft . evidence/VerifiedArtifacts#insert().","confidence":"exact","line":644}],"hash":"blake3:9ab7e24505a5f71cd2e61508e0fabb0e233106589d756559b7851f0b72d83d88"},{"id":"sym:cargo visioncraft . cli/evidence_parent().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/evidence_parent().","span":{"start_line":657,"start_col":1,"end_line":668,"end_col":2},"sig_hash":"blake3-16:db2e97ad57784510b3ed00e2d46b651b","body_hash":"blake3-16:88b1ddfbb57f2b8c7f2a5d0b9bb1ffb9","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":658},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":659},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":665},{"target":"sym:cargo visioncraft . cli/output_path().","confidence":"exact","line":667,"expands":"sym:cargo visioncraft . cli/output_path()."}],"hash":"blake3:7a67d1cb03b3bb52a8fe9d0834e11961466acafa8c8c2ffb261312621ece5f52"},{"id":"sym:cargo visioncraft . cli/run().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/run().","span":{"start_line":742,"start_col":1,"end_line":898,"end_col":2},"sig_hash":"blake3-16:ba17c27738cfde5ad2571ad58ca94d50","body_hash":"blake3-16:08da835ef954e7dd9cc676a5efc8ef47","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . process/","sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft . evidence/ExecutionReceipt#"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":743},{"target":"sym:cargo visioncraft . cli/read_plan().","confidence":"exact","line":744},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":751},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":755},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":760,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":763,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":764,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":766},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":773,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":773},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":774},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":775},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":779},{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":780},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":781,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":782},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":782,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/evidence_parent().","confidence":"exact","line":784,"expands":"sym:cargo visioncraft . cli/evidence_parent()."},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":784,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":789,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":790,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":792},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":797,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":800},{"target":"sym:cargo visioncraft . cli/executable().","confidence":"exact","line":801},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":806},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":813},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":814},{"target":"sym:cargo visioncraft . process/run_command().","confidence":"exact","line":820},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":824},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":824},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":828},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":828},{"target":"sym:cargo visioncraft . cli/process_status().","confidence":"exact","line":830},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":836,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . plan/QualityPlan#digest().","confidence":"inferred","line":855},{"target":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","confidence":"exact","line":879,"expands":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":881},{"target":"sym:cargo visioncraft . cli/write_new().","confidence":"exact","line":881,"expands":"sym:cargo visioncraft . cli/write_new()."},{"target":"sym:cargo visioncraft . cli/execution_exit().","confidence":"exact","line":882},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":894}],"hash":"blake3:f85f4c799e989e52e1d019de0ab972275cb43e5195f141cb2ea2d324af9bb903"},{"id":"sym:cargo visioncraft . cli/load_receipts().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/load_receipts().","span":{"start_line":900,"start_col":1,"end_line":930,"end_col":2},"sig_hash":"blake3-16:c5944f1ef230b917228e3114fc3f9133","body_hash":"blake3-16:8e82d035d63b0fd789327e31b5b9794c","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft . evidence/ExecutionReceipt#"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":904},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":911},{"target":"sym:cargo visioncraft . cli/confined().","confidence":"exact","line":916,"expands":"sym:cargo visioncraft . cli/confined()."},{"target":"sym:cargo visioncraft . cli/read_bounded().","confidence":"exact","line":923},{"target":"sym:cargo visioncraft . evidence/ExecutionReceipt#parse().","confidence":"exact","line":923},{"target":"sym:cargo visioncraft . cli/receipt_artifacts().","confidence":"exact","line":924},{"target":"sym:cargo visioncraft . cli/add_artifact().","confidence":"exact","line":925,"expands":"sym:cargo visioncraft . cli/add_artifact()."}],"hash":"blake3:cc786ac0e563e162c5bd861f9c216fe9ef10f557e6eeb37a0b004e691b4aa023"},{"id":"sym:cargo visioncraft . cli/evaluate_options().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/evaluate_options().","span":{"start_line":932,"start_col":1,"end_line":1077,"end_col":2},"sig_hash":"blake3-16:e24a4e8e44d00858f88e500a666ef939","body_hash":"blake3-16:9fd6438f6c66bc74969f7f025e4aabb5","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft .","sym:cargo visioncraft . plan/Subject#","sym:cargo visioncraft . evidence/VerifiedArtifacts#","sym:cargo visioncraft . cli/ContextFile#","sym:cargo visioncraft . evaluate/EvaluationContext#","sym:extern sealmap_corpus","sym:cargo visioncraft . evaluate/","sym:extern serde_json"],"calls":[{"target":"sym:cargo visioncraft . cli/root().","confidence":"exact","line":933},{"target":"sym:cargo visioncraft . cli/read_plan().","confidence":"exact","line":934},{"target":"sym:cargo visioncraft . cli/revision().","confidence":"exact","line":937,"expands":"sym:cargo visioncraft . cli/revision()."},{"target":"sym:cargo visioncraft . cli/inputs().","confidence":"exact","line":938,"expands":"sym:cargo visioncraft . cli/inputs()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":941},{"target":"sym:cargo visioncraft . cli/selected_dirty().","confidence":"exact","line":946,"expands":"sym:cargo visioncraft . cli/selected_dirty()."},{"target":"sym:cargo visioncraft . cli/json_bytes().","confidence":"exact","line":950},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":950},{"target":"sym:cargo visioncraft . cli/read_explicit().","confidence":"exact","line":956,"expands":"sym:cargo visioncraft . cli/read_explicit()."},{"target":"sym:cargo visioncraft . from_json().","confidence":"exact","line":957},{"target":"sym:cargo visioncraft . plan/Subject#validate().","confidence":"exact","line":958,"expands":"sym:cargo visioncraft . plan/Subject#validate()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":963},{"target":"sym:cargo visioncraft . evidence/VerifiedArtifacts#default().","confidence":"inferred","line":974},{"target":"sym:cargo visioncraft . cli/load_receipts().","confidence":"exact","line":977,"expands":"sym:cargo visioncraft . cli/load_receipts()."},{"target":"sym:cargo visioncraft . cli/ContextFile#default().","confidence":"inferred","line":979},{"target":"sym:cargo visioncraft . cli/read_explicit().","confidence":"exact","line":981,"expands":"sym:cargo visioncraft . cli/read_explicit()."},{"target":"sym:cargo visioncraft . from_json().","confidence":"exact","line":982},{"target":"sym:cargo visioncraft . cli/add_artifact().","confidence":"exact","line":989,"expands":"sym:cargo visioncraft . cli/add_artifact()."},{"target":"sym:cargo visioncraft . cli/git().","confidence":"exact","line":994,"expands":"sym:cargo visioncraft . cli/git()."},{"target":"sym:cargo visioncraft . evaluate/EvaluationContext#new().","confidence":"exact","line":1009},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":1016},{"target":"sym:extern sealmap_corpus::route::Family::named","confidence":"external","line":1022},{"target":"sym:cargo visioncraft . evaluate/","confidence":"exact","line":1026},{"target":"sym:extern serde_json::to_value","confidence":"external","line":1033},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":1040}],"hash":"blake3:17642162233672dd735dae4ee72a7a222c770a69d34827a8c3af548eac157f76"},{"id":"sym:cargo visioncraft . cli/execute().","kind":"sequence","document":"src/cli.rs.md","symbol":"sym:cargo visioncraft . cli/execute().","span":{"start_line":1079,"start_col":1,"end_line":1118,"end_col":2},"sig_hash":"blake3-16:46912e87ff2e1ea76267f5fc634b601d","body_hash":"blake3-16:38f8733b2f66f86957663943eeb3898d","participants":["sym:cargo visioncraft . cli/","sym:cargo visioncraft . deepsec/"],"calls":[{"target":"sym:cargo visioncraft . cli/init().","confidence":"exact","line":1088,"expands":"sym:cargo visioncraft . cli/init()."},{"target":"sym:cargo visioncraft . cli/read_plan().","confidence":"exact","line":1092},{"target":"sym:cargo visioncraft . cli/print_json().","confidence":"exact","line":1094},{"target":"sym:cargo visioncraft . cli/run().","confidence":"exact","line":1106,"expands":"sym:cargo visioncraft . cli/run()."},{"target":"sym:cargo visioncraft . cli/evaluate_options().","confidence":"exact","line":1113,"expands":"sym:cargo visioncraft . cli/evaluate_options()."},{"target":"sym:cargo visioncraft . deepsec/execute().","confidence":"exact","line":1115,"expands":"sym:cargo visioncraft . deepsec/execute()."},{"target":"sym:cargo visioncraft . cli/error().","confidence":"exact","line":1115}],"hash":"blake3:b33cd48ba99d0f8f35cf65973f7f754430fcf32c4df4237059c40674dbd2c4ce"}]},{"source":"src/deepsec.rs","document":"src/deepsec.rs.md","module":"sym:cargo visioncraft . deepsec/","source_hash":"blake3:854ecc6f32f348b299aed4807609cd7229d91f426a1af19ac2f3c9f4dd89e8e8","document_hash":"blake3:e3d7901d73b254d64cc5229600eb2d5c503825eedddc4dc88aece53a867835ac","fragments":[{"id":"structure:src/deepsec.rs","kind":"structure","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/","span":{"start_line":1,"start_col":1,"end_line":1084,"end_col":1},"sig_hash":"blake3-16:dfca6b22e7a0f75576ee19430ce800ad","body_hash":"blake3-16:0c6d444b98b33a51ead22c319b726fc0","participants":["sym:cargo visioncraft . deepsec/","sym:cargo visioncraft . deepsec/Attempt#","sym:cargo visioncraft . deepsec/DeepsecOptions#","sym:cargo visioncraft . deepsec/DeepsecPolicy#","sym:cargo visioncraft . deepsec/GateError#","sym:cargo visioncraft . deepsec/StrictJson#"],"hash":"blake3:6eecc34c285fec9c493ea0145ea40bfa7badb172c994b1257ff76b6d5cbb9329"},{"id":"sym:cargo visioncraft . deepsec/DeepsecPolicy#validate().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/DeepsecPolicy#validate().","span":{"start_line":142,"start_col":5,"end_line":229,"end_col":6},"sig_hash":"blake3-16:8e9590b4e5ea930dbb967d625e57fb57","body_hash":"blake3-16:0aaf1b920c2175079b0541e62429279d","participants":["sym:cargo visioncraft . deepsec/DeepsecPolicy#","sym:cargo visioncraft . deepsec/","sym:extern url"],"calls":[{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":146},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":149},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":152},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":155},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":161},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":167},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":180},{"target":"sym:extern url::Url::parse","confidence":"external","line":183},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":184},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":192},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":200},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":206},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":216},{"target":"sym:cargo visioncraft . deepsec/duration_ms().","confidence":"exact","line":223},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":224}],"hash":"blake3:abe7fa45bd5abad24561011927a3cf90fe983f66bed974955fbc0f150c2a401a"},{"id":"sym:cargo visioncraft . deepsec/findings().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/findings().","span":{"start_line":371,"start_col":1,"end_line":410,"end_col":2},"sig_hash":"blake3-16:d958a149d303f700360dacf89d848981","body_hash":"blake3-16:d23d0fceb0331f95373edce172a94932","participants":["sym:cargo visioncraft . deepsec/","sym:extern serde_json"],"calls":[{"target":"sym:extern serde_json::from_slice","confidence":"external","line":372},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":373},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":378},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":388},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":395},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":402},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":405}],"hash":"blake3:730cdc58cc3f43348c0dce498d29c1d82277e0e08fec90504dd8015cc12953c5"},{"id":"sym:cargo visioncraft . deepsec/Attempt#command().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/Attempt#command().","span":{"start_line":484,"start_col":5,"end_line":559,"end_col":6},"sig_hash":"blake3-16:e8c318eaf968b6ab917a2c6d444e8f2e","body_hash":"blake3-16:4aa6ec82fcec8f10bf66efbf85f15248","participants":["sym:cargo visioncraft . deepsec/Attempt#","sym:cargo visioncraft . deepsec/","sym:cargo visioncraft . process/","sym:cargo visioncraft . git_metadata/","sym:extern serde_json"],"calls":[{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":497},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":500},{"target":"sym:cargo visioncraft . git_metadata/prefix().","confidence":"exact","line":502},{"target":"sym:cargo visioncraft . git_metadata/fixed_environment().","confidence":"exact","line":507},{"target":"sym:cargo visioncraft . deepsec/environment().","confidence":"exact","line":510},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":522},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":523},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":520},{"target":"sym:cargo visioncraft . process/run_command_with_env().","confidence":"exact","line":525,"expands":"sym:cargo visioncraft . process/run_command_with_env()."},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":527},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":528},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":539},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":540},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":537},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":545},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":548},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":549},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":553},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":557}],"hash":"blake3:217704a889e0dea86a0b3a481dc04ae14029e0b4c6895a34f03be84c965d8db4"},{"id":"sym:cargo visioncraft . deepsec/validate_workspace_tree().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/validate_workspace_tree().","span":{"start_line":582,"start_col":1,"end_line":638,"end_col":2},"sig_hash":"blake3-16:50d3d1a4739265fe5f0d4d4ffac01a4b","body_hash":"blake3-16:02b16654c799bdd8c902b4aaec0ad794","participants":["sym:cargo visioncraft . deepsec/"],"calls":[{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":592},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":597},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":612},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":622}],"hash":"blake3:fa90a941449821bfb2ed4b05f47b26076630e6ce4eaacf825c4edb7f735845a4"},{"id":"sym:cargo visioncraft . deepsec/execute().","kind":"sequence","document":"src/deepsec.rs.md","symbol":"sym:cargo visioncraft . deepsec/execute().","span":{"start_line":640,"start_col":1,"end_line":1046,"end_col":2},"sig_hash":"blake3-16:0ba905b365d196f55d4ed680e35ea604","body_hash":"blake3-16:493d0570284912a2b98d4bafdbdadb73","participants":["sym:cargo visioncraft . deepsec/","sym:cargo visioncraft .","sym:cargo visioncraft . deepsec/DeepsecPolicy#","sym:extern serde_json","sym:cargo visioncraft . process/","sym:extern recorded","sym:extern tempfile","sym:cargo visioncraft . deepsec/Attempt#"],"calls":[{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":657},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":662},{"target":"sym:cargo visioncraft . from_json().","confidence":"exact","line":667},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":668},{"target":"sym:cargo visioncraft . deepsec/DeepsecPolicy#[Default]default().","confidence":"exact","line":669},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":688},{"target":"sym:cargo visioncraft . deepsec/root_for().","confidence":"exact","line":693},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":701},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":702},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":703},{"target":"sym:extern serde_json::to_string_pretty","confidence":"external","line":764},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":765},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":773},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":780},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":782},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":784},{"target":"sym:cargo visioncraft . deepsec/workspace_lock().","confidence":"exact","line":788},{"target":"sym:cargo visioncraft . deepsec/validate_workspace_tree().","confidence":"exact","line":789,"expands":"sym:cargo visioncraft . deepsec/validate_workspace_tree()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":791},{"target":"sym:cargo visioncraft . process/private_directory().","confidence":"exact","line":793},{"target":"sym:cargo visioncraft . process/private_file().","confidence":"exact","line":794},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":797},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":798},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":795},{"target":"sym:extern recorded::refuse_tracked_workspace","confidence":"external","line":812},{"target":"sym:extern tempfile::NamedTempFile::new_in","confidence":"external","line":815},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":819},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":824},{"target":"sym:extern serde_json::to_string_pretty","confidence":"external","line":830},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":831},{"target":"sym:extern tempfile::NamedTempFile::new_in","confidence":"external","line":833},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":838},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":839,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/supported_version().","confidence":"exact","line":859},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":860},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":865,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:extern recorded::select","confidence":"external","line":876},{"target":"sym:extern recorded::selected_dirty","confidence":"external","line":877},{"target":"sym:extern recorded::snapshot","confidence":"external","line":878},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":881},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":882},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":879},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":885},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":912,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":914},{"target":"sym:extern recorded::pending","confidence":"external","line":923},{"target":"sym:extern recorded::run_files","confidence":"external","line":927},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":944,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":946},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":949},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":952},{"target":"sym:extern recorded::snapshot","confidence":"external","line":957},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":960},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":961},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":958},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":964},{"target":"sym:extern recorded::validate_review","confidence":"external","line":966},{"target":"sym:cargo visioncraft . deepsec/Attempt#command().","confidence":"exact","line":986,"expands":"sym:cargo visioncraft . deepsec/Attempt#command()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":988},{"target":"sym:cargo visioncraft . deepsec/read_bounded().","confidence":"exact","line":990},{"target":"sym:cargo visioncraft . deepsec/findings().","confidence":"exact","line":991,"expands":"sym:cargo visioncraft . deepsec/findings()."},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":993},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":1036},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":1037},{"target":"sym:cargo visioncraft . deepsec/write_new().","confidence":"exact","line":1034},{"target":"sym:extern serde_json::to_string_pretty","confidence":"external","line":1041},{"target":"sym:cargo visioncraft . deepsec/error().","confidence":"exact","line":1042}],"hash":"blake3:ce047eecd8ae010b37aa075d5df7e2092b26cd07f1e49312f4ed75c239f42b14"}]},{"source":"src/deepsec_evidence.rs","document":"src/deepsec_evidence.rs.md","module":"sym:cargo visioncraft . deepsec_evidence/","source_hash":"blake3:0a9c380830ef2a7ac2da136735a50063ee9ef39345e526537439147442e2cfc6","document_hash":"blake3:45da54e14a76e33265288e5c650dfa41fafeff87f788763dba3d4e1c337db522","fragments":[{"id":"structure:src/deepsec_evidence.rs","kind":"structure","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/","span":{"start_line":1,"start_col":1,"end_line":459,"end_col":1},"sig_hash":"blake3-16:d29639f733f43b721a769946fd5c16ea","body_hash":"blake3-16:1c44870294f1ddd81e3ea7ab58d84d5f","participants":["sym:cargo visioncraft . deepsec_evidence/"],"hash":"blake3:5e5b81ab07b5b9c2d6a5358f82fa26d4fc0d7f559f6c6dbbca40749b76896e33"},{"id":"sym:cargo visioncraft . deepsec_evidence/confined().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/confined().","span":{"start_line":15,"start_col":1,"end_line":37,"end_col":2},"sig_hash":"blake3-16:339a3f31cc29d571f0d49cac65efa8cf","body_hash":"blake3-16:bfc51a62ae369d14245e4fe1e398ad60","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:cargo visioncraft .","sym:extern visioncraft"],"calls":[{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":16},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":20},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":29},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":33}],"hash":"blake3:b8c9c4216ed7327069ac7d1d1e50af8df2c6387d1660f7931168280d9a740822"},{"id":"sym:cargo visioncraft . deepsec_evidence/snapshot().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/snapshot().","span":{"start_line":38,"start_col":1,"end_line":60,"end_col":2},"sig_hash":"blake3-16:f9fca86ed05e6dea51f36aa77af98298","body_hash":"blake3-16:92e1f22220e61aed17b21bca7709b198","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft","sym:cargo visioncraft ."],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":40},{"target":"sym:cargo visioncraft . deepsec_evidence/confined().","confidence":"exact","line":46,"expands":"sym:cargo visioncraft . deepsec_evidence/confined()."},{"target":"sym:extern visioncraft::read_bounded","confidence":"inferred","line":46},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":49},{"target":"sym:cargo visioncraft . sha256().","confidence":"exact","line":56}],"hash":"blake3:5653bc15ccdd69ddf29a8b3373e42cc5d25cac283259f0cef32cb2a6d5713278"},{"id":"sym:cargo visioncraft . deepsec_evidence/tree().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/tree().","span":{"start_line":74,"start_col":1,"end_line":89,"end_col":2},"sig_hash":"blake3-16:c9241362b2d6b7023c14c9798510cad6","body_hash":"blake3-16:14a5d8a72b2d5f4a922d0bdfd024cdc4","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft","sym:cargo visioncraft . git_metadata/"],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":80},{"target":"sym:cargo visioncraft . git_metadata/tree_arguments().","confidence":"exact","line":86},{"target":"sym:cargo visioncraft . deepsec_evidence/git_bytes().","confidence":"exact","line":82},{"target":"sym:cargo visioncraft . git_metadata/tree_entries().","confidence":"exact","line":88},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":88}],"hash":"blake3:93094d0129be778f7e45340f168d6e49a3c565ad9dc10f4d638ab00b05231787"},{"id":"sym:cargo visioncraft . deepsec_evidence/working_hashes().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/working_hashes().","span":{"start_line":109,"start_col":1,"end_line":153,"end_col":2},"sig_hash":"blake3-16:4c70d5047b2b3417c963ca2f96cf378e","body_hash":"blake3-16:c3e3abb62af23493d77b0b662b5b227f","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft","sym:cargo visioncraft . git_metadata/"],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":115},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":124},{"target":"sym:cargo visioncraft . deepsec_evidence/confined().","confidence":"exact","line":128,"expands":"sym:cargo visioncraft . deepsec_evidence/confined()."},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":129},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":131},{"target":"sym:cargo visioncraft . git_metadata/raw_hash_arguments().","confidence":"exact","line":145},{"target":"sym:cargo visioncraft . deepsec_evidence/git_bytes().","confidence":"exact","line":141},{"target":"sym:cargo visioncraft . git_metadata/raw_hashes().","confidence":"exact","line":148},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":149}],"hash":"blake3:0fa02772dfb992827b56596a16f9ffc244a11d05edcdea4ad1a01d658aacda90"},{"id":"sym:cargo visioncraft . deepsec_evidence/selected_dirty().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/selected_dirty().","span":{"start_line":178,"start_col":1,"end_line":200,"end_col":2},"sig_hash":"blake3-16:792bfa7589c8daf748c3b6534981a489","body_hash":"blake3-16:de55a475cc1838ed7b6c795f69460107","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:cargo visioncraft . git_metadata/","sym:extern visioncraft"],"calls":[{"target":"sym:cargo visioncraft . git_metadata/tree_arguments().","confidence":"exact","line":190},{"target":"sym:cargo visioncraft . deepsec_evidence/git_bytes().","confidence":"exact","line":186},{"target":"sym:cargo visioncraft . git_metadata/tree_entries().","confidence":"exact","line":193},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":193},{"target":"sym:cargo visioncraft . deepsec_evidence/working_hashes().","confidence":"exact","line":196,"expands":"sym:cargo visioncraft . deepsec_evidence/working_hashes()."}],"hash":"blake3:dd4b9be49ce6c63e5b9ed6127384bdea7fd58dfc8ed96c9638f195d2482c8ffe"},{"id":"sym:cargo visioncraft . deepsec_evidence/select().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/select().","span":{"start_line":202,"start_col":1,"end_line":311,"end_col":2},"sig_hash":"blake3-16:cc9a89e8f0905b3cb12ddfe8572273b4","body_hash":"blake3-16:1541493d4ff26e52c453e87a65fb1f67","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft"],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":212},{"target":"sym:extern visioncraft::read_bounded","confidence":"inferred","line":216},{"target":"sym:cargo visioncraft . deepsec_evidence/git_bytes().","confidence":"exact","line":236},{"target":"sym:cargo visioncraft . deepsec_evidence/tree().","confidence":"exact","line":238,"expands":"sym:cargo visioncraft . deepsec_evidence/tree()."},{"target":"sym:cargo visioncraft . deepsec_evidence/index().","confidence":"exact","line":239},{"target":"sym:cargo visioncraft . deepsec_evidence/working_hashes().","confidence":"exact","line":248,"expands":"sym:cargo visioncraft . deepsec_evidence/working_hashes()."},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":274},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":280},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":288},{"target":"sym:cargo visioncraft . deepsec_evidence/confined().","confidence":"exact","line":294,"expands":"sym:cargo visioncraft . deepsec_evidence/confined()."},{"target":"sym:cargo visioncraft . deepsec_evidence/index().","confidence":"exact","line":297},{"target":"sym:cargo visioncraft . deepsec_evidence/working_hashes().","confidence":"exact","line":299,"expands":"sym:cargo visioncraft . deepsec_evidence/working_hashes()."},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":304}],"hash":"blake3:a61d6b13d9e68e996136de98b5272b816114bd5efcd2cd57ff4dc6bb9f9401cd"},{"id":"sym:cargo visioncraft . deepsec_evidence/run_files().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/run_files().","span":{"start_line":312,"start_col":1,"end_line":335,"end_col":2},"sig_hash":"blake3-16:6da82f7f40f25f96425a127fb162af24","body_hash":"blake3-16:f7cb0af119c19b3933742680610ae1da","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern visioncraft"],"calls":[{"target":"sym:extern visioncraft::error","confidence":"inferred","line":318},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":320},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":323},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":324},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":326}],"hash":"blake3:1624786ac1edaf9933c59e02458c9e8a45069628a872c991e089a8730adc656e"},{"id":"sym:cargo visioncraft . deepsec_evidence/validate_review().","kind":"sequence","document":"src/deepsec_evidence.rs.md","symbol":"sym:cargo visioncraft . deepsec_evidence/validate_review().","span":{"start_line":362,"start_col":1,"end_line":459,"end_col":2},"sig_hash":"blake3-16:48c209a2019e0cdfb19ce0ddd22d8346","body_hash":"blake3-16:9675ebd57301a2d020d9712a8b9c8a6c","participants":["sym:cargo visioncraft . deepsec_evidence/","sym:extern sealmap_corpus","sym:extern serde_json","sym:extern visioncraft","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . deepsec_evidence/run_files().","confidence":"exact","line":371,"expands":"sym:cargo visioncraft . deepsec_evidence/run_files()."},{"target":"sym:cargo visioncraft . deepsec_evidence/object().","confidence":"exact","line":372},{"target":"sym:extern sealmap_corpus::review::Artifact::iter","confidence":"external","line":378},{"target":"sym:cargo visioncraft . deepsec_evidence/file_record().","confidence":"exact","line":382},{"target":"sym:extern serde_json::to_vec_pretty","confidence":"external","line":389},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":390},{"target":"sym:extern visioncraft::write_new","confidence":"inferred","line":391},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":393},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":398},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":399},{"target":"sym:extern sealmap_corpus::review::Artifact::len","confidence":"external","line":404},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":406},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":418},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":425},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":428},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":439},{"target":"sym:extern visioncraft::error","confidence":"inferred","line":450}],"hash":"blake3:ae2141692794b47fd4e101b62646dbe9a0868370fb4b96e96f8a8df88584ea13"}]},{"source":"src/evaluate.rs","document":"src/evaluate.rs.md","module":"sym:cargo visioncraft . evaluate/","source_hash":"blake3:1950321301950506d38ec7deb1bfe79f0a16099c9d90b833356be23f7f90556d","document_hash":"blake3:93ddc20cd9d3d9148dddc3928faf9f996041aae25db36fcc4fb47cbd539c699e","fragments":[{"id":"structure:src/evaluate.rs","kind":"structure","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/","span":{"start_line":1,"start_col":1,"end_line":666,"end_col":1},"sig_hash":"blake3-16:9fe9b147ca2d959744dccbc9bb23ac64","body_hash":"blake3-16:b0b4dc86820dd895e04410652868d09d","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft . evaluate/CheckOutcome#","sym:cargo visioncraft . evaluate/CheckReport#","sym:cargo visioncraft . evaluate/EvaluationContext#","sym:cargo visioncraft . evaluate/ExpectationReport#","sym:cargo visioncraft . evaluate/GateOutcome#","sym:cargo visioncraft . evaluate/GateReport#"],"hash":"blake3:d5091dfff7bb58c6eb3e49cacb4b5589dcaf0e603efe16f2f4b6f4f74c0df81b"},{"id":"sym:cargo visioncraft . evaluate/check_receipt().","kind":"sequence","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/check_receipt().","span":{"start_line":160,"start_col":1,"end_line":273,"end_col":2},"sig_hash":"blake3-16:ee70d752233f4499288b800fcec0a414","body_hash":"blake3-16:d1fb01a0dcd74e443f9c5104f4378bc0","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft . evidence/ExecutionReceipt#","sym:cargo visioncraft . plan/","sym:cargo visioncraft . evidence/VerifiedArtifacts#"],"calls":[{"target":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","confidence":"exact","line":168,"expands":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate()."},{"target":"sym:cargo visioncraft . plan/same_inputs().","confidence":"exact","line":177},{"target":"sym:cargo visioncraft . evaluate/context_limits().","confidence":"exact","line":183},{"target":"sym:cargo visioncraft . evaluate/age_limit().","confidence":"exact","line":184},{"target":"sym:cargo visioncraft . evidence/VerifiedArtifacts#byte_len().","confidence":"inferred","line":211}],"hash":"blake3:03deb8052d7f7256279b5dd683bac32c7d37e95026d1630b4e041a7b51e85f0e"},{"id":"sym:cargo visioncraft . evaluate/assessment_binding().","kind":"sequence","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/assessment_binding().","span":{"start_line":298,"start_col":1,"end_line":324,"end_col":2},"sig_hash":"blake3-16:e2d6db985ebd381da5d83e24ce107563","body_hash":"blake3-16:7a88080516bd7bd0b90dc02576dd1792","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":307},{"target":"sym:cargo visioncraft . evaluate/context_limits().","confidence":"exact","line":312},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":311},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":315},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":316},{"target":"sym:cargo visioncraft . evaluate/age_limit().","confidence":"exact","line":321},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":320}],"hash":"blake3:d2781efc3b66ea92b85e53a655c7735a7d82808b4e90a0f44d0a9099f23ad5d7"},{"id":"sym:cargo visioncraft . evaluate/expectation_report().","kind":"sequence","document":"src/evaluate.rs.md","symbol":"sym:cargo visioncraft . evaluate/expectation_report().","span":{"start_line":326,"start_col":1,"end_line":528,"end_col":2},"sig_hash":"blake3-16:60bd522cd3ba06f3d9da1f7b3e90b52b","body_hash":"blake3-16:e4d1797b13f584d6f345f1601b1187e9","participants":["sym:cargo visioncraft . evaluate/","sym:cargo visioncraft .","sym:extern sealmap_corpus"],"calls":[{"target":"sym:cargo visioncraft . evaluate/referenced_check().","confidence":"exact","line":337},{"target":"sym:cargo visioncraft . evaluate/referenced_check().","confidence":"exact","line":340},{"target":"sym:cargo visioncraft . evaluate/referenced_check().","confidence":"exact","line":343},{"target":"sym:cargo visioncraft . evaluate/assessment_binding().","confidence":"exact","line":375,"expands":"sym:cargo visioncraft . evaluate/assessment_binding()."},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":385},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":386},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":387},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":384},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":390},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":395},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":404},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":408},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":415},{"target":"sym:extern sealmap_corpus::route::cross_family_with","confidence":"external","line":425},{"target":"sym:cargo visioncraft . evaluate/assessment_binding().","confidence":"exact","line":483,"expands":"sym:cargo visioncraft . evaluate/assessment_binding()."},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":494},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":494},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":493}],"hash":"blake3:621bb154f0bc58def0d9b99839bfb5f7f07500da87de83f718956d20bb7d43f5"}]},{"source":"src/evidence.rs","document":"src/evidence.rs.md","module":"sym:cargo visioncraft . evidence/","source_hash":"blake3:edfe990a885f2bcad685855fe0c87e11878174d676e4414f4f9448e818ca520a","document_hash":"blake3:92db7d2db5b346b252f2fd1d9472793cfc0dda06b4ac5f891e0e98a8629fc804","fragments":[{"id":"structure:src/evidence.rs","kind":"structure","document":"src/evidence.rs.md","symbol":"sym:cargo visioncraft . evidence/","span":{"start_line":1,"start_col":1,"end_line":292,"end_col":1},"sig_hash":"blake3-16:af11808614b221a0d9791b5c9c0aa422","body_hash":"blake3-16:07ca5c0150b9e722b1428c85557ebe66","participants":["sym:cargo visioncraft . evidence/","sym:cargo visioncraft . evidence/Actor#","sym:cargo visioncraft . evidence/AuditReceipt#","sym:cargo visioncraft . evidence/AuditVerdict#","sym:cargo visioncraft . evidence/ExecutionReceipt#","sym:cargo visioncraft . evidence/ManualObservation#","sym:cargo visioncraft . evidence/ProcessStatus#","sym:cargo visioncraft . evidence/ReportedResult#","sym:cargo visioncraft . evidence/VerifiedArtifacts#"],"hash":"blake3:4cac75df033fe3d821a9d0b2c1862cba2880e53086a68efdbae14c83e5830ef8"},{"id":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","kind":"sequence","document":"src/evidence.rs.md","symbol":"sym:cargo visioncraft . evidence/ExecutionReceipt#validate().","span":{"start_line":107,"start_col":5,"end_line":178,"end_col":6},"sig_hash":"blake3-16:ba67f81a1ab12cfa2f20da686b32f5f9","body_hash":"blake3-16:85e6fc9a46be325577dbc0b80d49e394","participants":["sym:cargo visioncraft . evidence/ExecutionReceipt#","sym:cargo visioncraft .","sym:cargo visioncraft . plan/Subject#","sym:cargo visioncraft . plan/Invocation#","sym:cargo visioncraft . plan/"],"calls":[{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":113},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":115},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":115},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":114},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":118},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":118},{"target":"sym:cargo visioncraft . plan/Subject#validate().","confidence":"exact","line":119,"expands":"sym:cargo visioncraft . plan/Subject#validate()."},{"target":"sym:cargo visioncraft . plan/Invocation#validate().","confidence":"exact","line":120,"expands":"sym:cargo visioncraft . plan/Invocation#validate()."},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":122},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":121},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":126},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":126},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":129},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":129},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":131},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":135},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":140},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":144},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":149},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":155},{"target":"sym:cargo visioncraft . plan/validate_input_paths().","confidence":"exact","line":157},{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":161},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":160},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":167},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":166},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":172},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":172},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":171},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":175}],"hash":"blake3:5d5543a5441c2972246e77d27188c7df4e53e2c8f859470ae0c0453e4c16b416"}]},{"source":"src/git_metadata.rs","document":"src/git_metadata.rs.md","module":"sym:cargo visioncraft . git_metadata/","source_hash":"blake3:5180f0e3dc3c8f0caf13e2dd1a6ab29b1799760491ce380efcc91c012988c0ae","document_hash":"blake3:fefb5e36f16dc3eae61d06214e157cf99d2a0465415ab757ca8c09fedfe131d9","fragments":[{"id":"structure:src/git_metadata.rs","kind":"structure","document":"src/git_metadata.rs.md","symbol":"sym:cargo visioncraft . git_metadata/","span":{"start_line":1,"start_col":1,"end_line":142,"end_col":1},"sig_hash":"blake3-16:c95500707a557a0575618bc2539225f2","body_hash":"blake3-16:b91d5fd49d1d941bda559f82e91581f9","participants":["sym:cargo visioncraft . git_metadata/","sym:cargo visioncraft . git_metadata/Entry#"],"hash":"blake3:7e0f3b6825c4dd9e71920dfeeffb613d786b7a627eaa021c171f22a55898fe4b"}]},{"source":"src/lib.rs","document":"src/lib.rs.md","module":"sym:cargo visioncraft .","source_hash":"blake3:bd0cbb39c4723d919330852c9a157a2284d5b8102817d2c74eb7dd89a715bffb","document_hash":"blake3:a2cf789c4c08e0dc3d6f4a053570d75dc8cfd0cb2d49021eeec4364ad51fa0e3","fragments":[{"id":"structure:src/lib.rs","kind":"structure","document":"src/lib.rs.md","symbol":"sym:cargo visioncraft .","span":{"start_line":1,"start_col":1,"end_line":132,"end_col":1},"sig_hash":"blake3-16:ef5f0989f89148798c9d4374da243656","body_hash":"blake3-16:07498bcaf3ef330f07f8945432f31636","participants":["sym:cargo visioncraft .","sym:cargo visioncraft . ContractError#"],"hash":"blake3:9f5d5b04a6ee671ff43fa2cda20f9bd1e2116468c93c310aafc175d99a64ccc4"}]},{"source":"src/main.rs","document":"src/main.rs.md","module":"sym:cargo visioncraft_main .","source_hash":"blake3:4bb59bf863aec89c7e0f6ea0dc232c477e58b0d54775b003a29d43b892e22326","document_hash":"blake3:74400fa28d70e441bfb8d12dd9804989463f276c65f910faed90e827f7563fb8","fragments":[{"id":"structure:src/main.rs","kind":"structure","document":"src/main.rs.md","symbol":"sym:cargo visioncraft_main .","span":{"start_line":1,"start_col":1,"end_line":39,"end_col":1},"sig_hash":"blake3-16:be7e0aa42067d3874629adeff2b5a523","body_hash":"blake3-16:fc2e76f655eeaf6fb63b94d01fdf8e29","participants":["sym:cargo visioncraft_main ."],"hash":"blake3:6072a92081ad96885a435ab18fa15f7156552c9f5a91ffd3b893d30664f7c127"}]},{"source":"src/plan.rs","document":"src/plan.rs.md","module":"sym:cargo visioncraft . plan/","source_hash":"blake3:a0eaf6b6e34139a3b02ddc3d521d69dc4c064884b96dfe85585b1a1e7da2107d","document_hash":"blake3:52a11da34333ac5b351ee8aecb9f323047782e5c9a5a9c3d35b3707c159fa8f8","fragments":[{"id":"structure:src/plan.rs","kind":"structure","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/","span":{"start_line":1,"start_col":1,"end_line":413,"end_col":1},"sig_hash":"blake3-16:a24f0f42e161b5767c66583d880ff1c1","body_hash":"blake3-16:244666ed06402316b2c9d9f1e3d97726","participants":["sym:cargo visioncraft . plan/","sym:cargo visioncraft . plan/CheckSpec#","sym:cargo visioncraft . plan/Evaluator#","sym:cargo visioncraft . plan/EvidenceCategory#","sym:cargo visioncraft . plan/Expectation#","sym:cargo visioncraft . plan/GatePolicy#","sym:cargo visioncraft . plan/Invocation#","sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft . plan/Stabilizer#","sym:cargo visioncraft . plan/Subject#"],"hash":"blake3:c3b2d48210fcb0809c8dffe5957419f886988159fb60f056c51dd599ada41860"},{"id":"sym:cargo visioncraft . plan/Subject#validate().","kind":"sequence","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/Subject#validate().","span":{"start_line":36,"start_col":5,"end_line":58,"end_col":6},"sig_hash":"blake3-16:cc5a01905f372f11d7204d0e8ae9b415","body_hash":"blake3-16:5c8417ac75b7f4969f36b4094d1bba88","participants":["sym:cargo visioncraft . plan/Subject#","sym:cargo visioncraft .","sym:cargo visioncraft . plan/"],"calls":[{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":41},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":41},{"target":"sym:cargo visioncraft . hex().","confidence":"exact","line":43},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":42},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":47},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":46},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":50},{"target":"sym:cargo visioncraft . artifact_shape().","confidence":"exact","line":55},{"target":"sym:cargo visioncraft . plan/validate_inputs().","confidence":"exact","line":57}],"hash":"blake3:322d9507a0187eaa308b3d532d47b123850c5a0d98d5ae483d9298c64ffe0ff3"},{"id":"sym:cargo visioncraft . plan/Invocation#validate().","kind":"sequence","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/Invocation#validate().","span":{"start_line":104,"start_col":5,"end_line":137,"end_col":6},"sig_hash":"blake3-16:df6aee1d4a2a9d4b92536e69433d3c6a","body_hash":"blake3-16:49668b9727c1ac54be4cd4c716e96fee","participants":["sym:cargo visioncraft . plan/Invocation#","sym:cargo visioncraft ."],"calls":[{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":109},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":109},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":110},{"target":"sym:cargo visioncraft . relative_path().","confidence":"exact","line":115},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":114},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":120},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":127},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":129},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":133}],"hash":"blake3:3354fc277d9bd09a45bbea06e5bc7342f7c586064f59d475a64b2bf33d0fda57"},{"id":"sym:cargo visioncraft . plan/QualityPlan#validate().","kind":"sequence","document":"src/plan.rs.md","symbol":"sym:cargo visioncraft . plan/QualityPlan#validate().","span":{"start_line":291,"start_col":5,"end_line":398,"end_col":6},"sig_hash":"blake3-16:fa4cb29f8ee4f18407e9aa68bcbe8d75","body_hash":"blake3-16:16e4b5b86916c3ea0a2107386a4cc734","participants":["sym:cargo visioncraft . plan/QualityPlan#","sym:cargo visioncraft .","sym:cargo visioncraft . plan/Subject#"],"calls":[{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":296},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":297},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":301},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":301},{"target":"sym:cargo visioncraft . plan/Subject#validate().","confidence":"exact","line":302,"expands":"sym:cargo visioncraft . plan/Subject#validate()."},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":303},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":307},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":317},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":316},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":327},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":331},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":335},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":338},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":346},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":354},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":353},{"target":"sym:cargo visioncraft . identifier().","confidence":"exact","line":362},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":361},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":365},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":365},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":367},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":374},{"target":"sym:cargo visioncraft . nonempty().","confidence":"exact","line":380},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":379},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":385},{"target":"sym:cargo visioncraft . require().","confidence":"exact","line":391}],"hash":"blake3:a69180a482bd092c9035df0f4320ba289ec9d3162ec8ec2442e80c95752b5e56"}]},{"source":"src/process.rs","document":"src/process.rs.md","module":"sym:cargo visioncraft . process/","source_hash":"blake3:3653d7e09689bd761ffeff3e445975bfa935814efde0ebb6aa9c1ce2adcd903b","document_hash":"blake3:438a75e22f9cfb2c75d6fe27cf7d6cb8d864066f4ba086e2ce076f342cee4883","fragments":[{"id":"structure:src/process.rs","kind":"structure","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/","span":{"start_line":1,"start_col":1,"end_line":841,"end_col":1},"sig_hash":"blake3-16:7e2098952f191664fce2401b4fe2c94b","body_hash":"blake3-16:a2f7b2abd509cf28fdb75c3878c400f7","participants":["sym:cargo visioncraft . process/","sym:cargo visioncraft . process/CapturedRun#","sym:cargo visioncraft . process/Termination#","sym:cargo visioncraft . process/lifecycle_tests/","sym:cargo visioncraft . process/linux_proc/"],"hash":"blake3:16d6e3cdcb6791ae483d161c57a6207500a8f8ee76e3321bb2e9ed2fb52fdaab"},{"id":"sym:cargo visioncraft . process/group_running().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/group_running().","span":{"start_line":305,"start_col":1,"end_line":318,"end_col":2},"sig_hash":"blake3-16:3224405d963ab2ce8b37fed93142b1b9","body_hash":"blake3-16:47fc09c9e4a3a5db3e26d94adda7f814","participants":["sym:cargo visioncraft . process/","sym:extern nix","sym:cargo visioncraft . process/linux_proc/"],"calls":[{"target":"sym:extern nix::unistd::Pid::from_raw","confidence":"external","line":313},{"target":"sym:extern nix::sys::signal::killpg","confidence":"external","line":313},{"target":"sym:cargo visioncraft . process/group_probe().","confidence":"exact","line":313},{"target":"sym:cargo visioncraft . process/linux_proc/group_running().","confidence":"exact","line":317,"expands":"sym:cargo visioncraft . process/linux_proc/group_running()."}],"hash":"blake3:160b1938d01776868bd9ac1e251b2293252b7cbbffe4840e44f74fc947cbcc8b"},{"id":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","span":{"start_line":421,"start_col":5,"end_line":429,"end_col":6},"sig_hash":"blake3-16:49458981d13cf9ce4c6c0a96ca26feec","body_hash":"blake3-16:f2879a39f584e155dc13e267a52ae2ef","participants":["sym:cargo visioncraft . process/linux_proc/","sym:extern nix","sym:extern io"],"calls":[{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":423},{"target":"sym:extern nix::unistd::Pid::from_raw","confidence":"external","line":422},{"target":"sym:extern nix::unistd::getpgid","confidence":"external","line":422},{"target":"sym:extern io::Error::from","confidence":"external","line":427}],"hash":"blake3:a798cd074970aad872574e1501ad3536ce7cd6d6435fcfd5a05010cc94c05bd3"},{"id":"sym:cargo visioncraft . process/linux_proc/tasks_dead().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/linux_proc/tasks_dead().","span":{"start_line":431,"start_col":5,"end_line":451,"end_col":6},"sig_hash":"blake3-16:a9f9ab596bca87189a028b260242a28e","body_hash":"blake3-16:123a9041f4c2fbded78b9b11120156c3","participants":["sym:cargo visioncraft . process/linux_proc/"],"calls":[{"target":"sym:cargo visioncraft . process/linux_proc/ids().","confidence":"exact","line":432},{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":434},{"target":"sym:cargo visioncraft . process/linux_proc/bounded_read().","confidence":"exact","line":437},{"target":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","confidence":"exact","line":440,"expands":"sym:cargo visioncraft . process/linux_proc/no_longer_member()."},{"target":"sym:cargo visioncraft . process/linux_proc/state().","confidence":"exact","line":446},{"target":"sym:cargo visioncraft . process/linux_proc/dead().","confidence":"exact","line":446}],"hash":"blake3:d005e864bcd330ec387e43270ff69774f1c4919c5f6b84ab27bcd66989a7fc36"},{"id":"sym:cargo visioncraft . process/linux_proc/dead_members().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/linux_proc/dead_members().","span":{"start_line":453,"start_col":5,"end_line":487,"end_col":6},"sig_hash":"blake3-16:3b267a99719de21556fd8c379c12f9cc","body_hash":"blake3-16:f9cf83781959814ebc4fb431277ff7bf","participants":["sym:cargo visioncraft . process/linux_proc/"],"calls":[{"target":"sym:cargo visioncraft . process/linux_proc/ids().","confidence":"exact","line":455},{"target":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","confidence":"exact","line":456,"expands":"sym:cargo visioncraft . process/linux_proc/no_longer_member()."},{"target":"sym:cargo visioncraft . process/linux_proc/bounded_read().","confidence":"exact","line":460},{"target":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","confidence":"exact","line":463,"expands":"sym:cargo visioncraft . process/linux_proc/no_longer_member()."},{"target":"sym:cargo visioncraft . process/linux_proc/state().","confidence":"exact","line":469},{"target":"sym:cargo visioncraft . process/linux_proc/dead().","confidence":"exact","line":469},{"target":"sym:cargo visioncraft . process/linux_proc/tasks_dead().","confidence":"exact","line":474,"expands":"sym:cargo visioncraft . process/linux_proc/tasks_dead()."},{"target":"sym:cargo visioncraft . process/linux_proc/no_longer_member().","confidence":"exact","line":478,"expands":"sym:cargo visioncraft . process/linux_proc/no_longer_member()."}],"hash":"blake3:ee87f97968bf4f63ce23188e9b3e96ed180abb5ab2ad8c9f08b5b91944593512"},{"id":"sym:cargo visioncraft . process/linux_proc/group_running().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/linux_proc/group_running().","span":{"start_line":489,"start_col":5,"end_line":521,"end_col":6},"sig_hash":"blake3-16:99a2a0a6fb625ac643156e3927572fa6","body_hash":"blake3-16:66cd29c67e27972c551df4e13580259c","participants":["sym:cargo visioncraft . process/linux_proc/","sym:extern nix","sym:cargo visioncraft . process/"],"calls":[{"target":"sym:cargo visioncraft . process/linux_proc/bounded_read().","confidence":"exact","line":490},{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":491},{"target":"sym:cargo visioncraft . process/linux_proc/unrestricted().","confidence":"exact","line":491},{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":492},{"target":"sym:cargo visioncraft . process/linux_proc/bounded_read().","confidence":"exact","line":496},{"target":"sym:cargo visioncraft . process/linux_proc/state().","confidence":"exact","line":495},{"target":"sym:cargo visioncraft . process/linux_proc/dead_members().","confidence":"exact","line":502,"expands":"sym:cargo visioncraft . process/linux_proc/dead_members()."},{"target":"sym:extern nix::unistd::Pid::from_raw","confidence":"external","line":506},{"target":"sym:extern nix::sys::signal::killpg","confidence":"external","line":506},{"target":"sym:cargo visioncraft . process/group_probe().","confidence":"exact","line":506},{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":508},{"target":"sym:cargo visioncraft . process/linux_proc/unknown().","confidence":"exact","line":520}],"hash":"blake3:6f2204d56010527ea7f44aa5c8de7f0dc91868d5e56ecdf52bf420dae22da166"},{"id":"sym:cargo visioncraft . process/run_command_with_env().","kind":"sequence","document":"src/process.rs.md","symbol":"sym:cargo visioncraft . process/run_command_with_env().","span":{"start_line":613,"start_col":1,"end_line":841,"end_col":2},"sig_hash":"blake3-16:60939e55bba0ee305de92ce58430f493","body_hash":"blake3-16:c9e8cc5c6839177d39d7915e7005f1eb","participants":["sym:cargo visioncraft . process/","sym:cargo visioncraft . plan/Invocation#"],"calls":[{"target":"sym:cargo visioncraft . plan/Invocation#validate().","confidence":"exact","line":640,"expands":"sym:cargo visioncraft . plan/Invocation#validate()."},{"target":"sym:cargo visioncraft . process/unix_now().","confidence":"exact","line":643},{"target":"sym:cargo visioncraft . process/private_file().","confidence":"exact","line":647},{"target":"sym:cargo visioncraft . process/private_file().","confidence":"exact","line":648},{"target":"sym:cargo visioncraft . process/unix_now().","confidence":"exact","line":700},{"target":"sym:cargo visioncraft . process/capture().","confidence":"exact","line":709},{"target":"sym:cargo visioncraft . process/capture().","confidence":"exact","line":717},{"target":"sym:cargo visioncraft . process/leader_exited().","confidence":"exact","line":737},{"target":"sym:cargo visioncraft . process/group_running().","confidence":"exact","line":752,"expands":"sym:cargo visioncraft . process/group_running()."},{"target":"sym:cargo visioncraft . process/signal_owned_group().","confidence":"exact","line":783},{"target":"sym:cargo visioncraft . process/leader_exited().","confidence":"exact","line":790},{"target":"sym:cargo visioncraft . process/signal_owned_group().","confidence":"exact","line":805},{"target":"sym:cargo visioncraft . process/unix_now().","confidence":"exact","line":837}],"hash":"blake3:e1b4ab00eb6484b3b22eea0282da8ce4e823250c7fb9fcd15057d5bfa6252a7b"}]}]} diff --git a/docs/diagrams/generated/_overview.md b/docs/diagrams/generated/_overview.md index 3b93de0..79be895 100644 --- a/docs/diagrams/generated/_overview.md +++ b/docs/diagrams/generated/_overview.md @@ -4,7 +4,7 @@ kind: overview codebase: visioncraft --- # visioncraft overview -10 files · 168 symbols · 632 relations · 80 flows · 543 calls +10 files · 182 symbols · 691 relations · 90 flows · 583 calls ## crates ```mermaid @@ -30,8 +30,8 @@ flowchart LR visioncraft -->|"5"| clap visioncraft -->|"1"| fs visioncraft -->|"11"| io - visioncraft -->|"24"| nix - visioncraft -->|"5"| recorded + visioncraft -->|"32"| nix + visioncraft -->|"7"| recorded visioncraft -->|"37"| sealmap_corpus visioncraft -->|"14"| serde visioncraft -->|"20"| serde_json @@ -62,7 +62,7 @@ flowchart LR visioncraft__cli -->|"2"| visioncraft__deepsec visioncraft__cli -->|"3"| visioncraft__evaluate visioncraft__cli -->|"16"| visioncraft__evidence - visioncraft__cli -->|"2"| visioncraft__git_metadata + visioncraft__cli -->|"4"| visioncraft__git_metadata visioncraft__cli -->|"13"| visioncraft__plan visioncraft__cli -->|"8"| visioncraft__process visioncraft__deepsec -->|"3"| visioncraft @@ -70,12 +70,14 @@ flowchart LR visioncraft__deepsec -->|"1"| visioncraft__plan visioncraft__deepsec -->|"8"| visioncraft__process visioncraft__deepsec_evidence -->|"4"| visioncraft + visioncraft__deepsec_evidence -->|"9"| visioncraft__git_metadata visioncraft__evaluate -->|"10"| visioncraft visioncraft__evaluate -->|"15"| visioncraft__evidence visioncraft__evaluate -->|"20"| visioncraft__plan visioncraft__evidence -->|"20"| visioncraft visioncraft__evidence -->|"2"| visioncraft__evaluate visioncraft__evidence -->|"10"| visioncraft__plan + visioncraft__git_metadata -->|"3"| visioncraft visioncraft__plan -->|"31"| visioncraft visioncraft__process -->|"4"| visioncraft__plan ``` diff --git a/docs/diagrams/generated/src/cli.rs.md b/docs/diagrams/generated/src/cli.rs.md index dec23f9..13a14f5 100644 --- a/docs/diagrams/generated/src/cli.rs.md +++ b/docs/diagrams/generated/src/cli.rs.md @@ -3,8 +3,8 @@ sealmap: 2 source: src/cli.rs module: "sym:cargo visioncraft . cli/" language: rust -source_hash: blake3:e5a287dcb11e681724fa694daeace991975ed75a6cc4cf342d3328a778ce0c6d -lines: 1135 +source_hash: blake3:88c24a1ad87b7d1fdf86ccd6ec14585657147358a0f29d10bee5669885c5c451 +lines: 1118 fragments: 17 --- # `sym:cargo visioncraft . cli/` · src/cli.rs @@ -169,26 +169,21 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/selected_dirty().` -`fn selected_dirty(root: &Path, paths: &[String], cancelled: &AtomicBool) -> Result` · L419-L484 +`fn selected_dirty(root: &Path, paths: &[String], cancelled: &AtomicBool) -> Result` · L419-L467 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod + participant visioncraft__git_metadata as git_metadata mod participant visioncraft as visioncraft mod + visioncraft__cli->>visioncraft__git_metadata: git_metadata::tree_arguments(#quot;HEAD#quot;, paths) visioncraft__cli->>visioncraft__cli: git(root, &args, cancelled)? opt !output.success visioncraft__cli->>visioncraft__cli: error(70, #quot;could not in…) Note over visioncraft__cli: return Err(error(70, #quot;could not inspect selected Git in… end - loop for row in output.stdout.split(| b | * b == 0).filter(|… - opt via ok_or_else - visioncraft__cli->>visioncraft__cli: error(70, #quot;invalid Git …) - end - opt via map_err - visioncraft__cli->>visioncraft__cli: error(70, #quot;invalid Git …) - end - opt via map_err - visioncraft__cli->>visioncraft__cli: error(70, #quot;selected Git…) - end + visioncraft__cli->>visioncraft__git_metadata: git_metadata::tree_entries(&output.stdout) + opt via map_err + visioncraft__cli->>visioncraft__cli: error(70, message) end loop for path in paths opt let-else @@ -236,7 +231,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/inputs().` -`fn inputs(root: &Path, paths: &[String], missing_ok: bool) -> Result, CliError>` · L493-L521 +`fn inputs(root: &Path, paths: &[String], missing_ok: bool) -> Result, CliError>` · L476-L504 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -263,7 +258,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/source_snapshot().` -`fn source_snapshot(root: &Path, paths: &[String], revision: &str, expected: &[Artifact],) -> Result, CliError>` · L523-L557 +`fn source_snapshot(root: &Path, paths: &[String], revision: &str, expected: &[Artifact],) -> Result, CliError>` · L506-L540 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -287,7 +282,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/init().` -`fn init(options: InitOptions, cancelled: &AtomicBool) -> Result` · L564-L652 +`fn init(options: InitOptions, cancelled: &AtomicBool) -> Result` · L547-L635 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -340,7 +335,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/add_artifact().` -`fn add_artifact(verified: &mut VerifiedArtifacts, root: &Path, artifact: &Artifact,) -> Result<(), CliError>` · L654-L662 +`fn add_artifact(verified: &mut VerifiedArtifacts, root: &Path, artifact: &Artifact,) -> Result<(), CliError>` · L637-L645 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -353,7 +348,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/evidence_parent().` -`fn evidence_parent(root: &Path, path: &str) -> Result` · L674-L685 +`fn evidence_parent(root: &Path, path: &str) -> Result` · L657-L668 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -371,7 +366,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/run().` -`fn run(options: RunOptions, cancelled: &AtomicBool) -> Result` · L759-L915 +`fn run(options: RunOptions, cancelled: &AtomicBool) -> Result` · L742-L898 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -453,7 +448,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/load_receipts().` -`fn load_receipts(directory: &Path, verified: &mut VerifiedArtifacts,) -> Result, CliError>` · L917-L947 +`fn load_receipts(directory: &Path, verified: &mut VerifiedArtifacts,) -> Result, CliError>` · L900-L930 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -479,7 +474,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/evaluate_options().` -`fn evaluate_options(options: EvaluateOptions, cancelled: &AtomicBool) -> Result` · L949-L1094 +`fn evaluate_options(options: EvaluateOptions, cancelled: &AtomicBool) -> Result` · L932-L1077 ```mermaid sequenceDiagram participant visioncraft__cli as cli mod @@ -542,7 +537,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . cli/execute().` -`pub fn execute(cli: Cli, cancelled: &AtomicBool) -> Result` · L1096-L1135 +`pub fn execute(cli: Cli, cancelled: &AtomicBool) -> Result` · L1079-L1118 > Dispatch an explicit CLI operation. ```mermaid sequenceDiagram diff --git a/docs/diagrams/generated/src/deepsec.rs.md b/docs/diagrams/generated/src/deepsec.rs.md index f1840ae..33694c3 100644 --- a/docs/diagrams/generated/src/deepsec.rs.md +++ b/docs/diagrams/generated/src/deepsec.rs.md @@ -3,9 +3,9 @@ sealmap: 2 source: src/deepsec.rs module: "sym:cargo visioncraft . deepsec/" language: rust -source_hash: blake3:f6a856414c586500e5bbcb69b8f4cee3caf40b2de0b8895792ad0ca34e45c977 -lines: 1063 -fragments: 5 +source_hash: blake3:854ecc6f32f348b299aed4807609cd7229d91f426a1af19ac2f3c9f4dd89e8e8 +lines: 1084 +fragments: 6 --- # `sym:cargo visioncraft . deepsec/` · src/deepsec.rs > Executed Deepsec 2.3.10 gates with explicit policy and retained error states. @@ -219,8 +219,35 @@ sequenceDiagram end ``` +## `sym:cargo visioncraft . deepsec/validate_workspace_tree().` +`fn validate_workspace_tree(workspace: &Path) -> Result<(), GateError>` · L582-L638 +```mermaid +sequenceDiagram + participant visioncraft__deepsec as deepsec mod + loop while let Some((directory, depth)) = pending.pop() + opt depth> 64 + visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;review works…) + Note over visioncraft__deepsec: return Err(error(78, #quot;review workspace exceeds traversa… + end + loop for entry in fs::read_dir(directory).map_err(io_error)? + opt count> 100_000 + visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;review works…) + Note over visioncraft__deepsec: return Err(error(78, #quot;review workspace exceeds traversa… + end + opt depth == 0 && ![#quot;data#quot;, #quot;reports#quot;, #quot;deepsec.config.m… + visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;review works…) + Note over visioncraft__deepsec: return Err(error(78, #quot;review workspace contains unmanag… + end + opt meta.file_type().is_symlink() ||!(meta.is_dir() || m… + visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;review works…) + Note over visioncraft__deepsec: return Err(error(78, #quot;review workspace contains redirec… + end + end + end +``` + ## `sym:cargo visioncraft . deepsec/execute().` -`pub fn execute(options: &DeepsecOptions, cancelled: &AtomicBool) -> Result` · L618-L1025 +`pub fn execute(options: &DeepsecOptions, cancelled: &AtomicBool) -> Result` · L640-L1046 > Execute an explicitly requested security gate, returning its legacy exit code. ```mermaid sequenceDiagram @@ -229,9 +256,9 @@ sequenceDiagram participant visioncraft__deepsec___tDeepsecPolicy as DeepsecPolicy participant _serde_json as serde_json ext participant visioncraft__process as process mod + participant _recorded as recorded ext participant _tempfile as tempfile ext participant visioncraft__deepsec___tAttempt as Attempt - participant _recorded as recorded ext opt modes.into_iter().filter(| x | * x).count() != 1 || … visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;choose exact…) Note over visioncraft__deepsec: return Err(error(78, #quot;choose exactly one nonempty sourc… @@ -292,23 +319,24 @@ sequenceDiagram visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;plan seriali…) end visioncraft__deepsec->>visioncraft__deepsec: write_new(&join(), &_)? - visioncraft__deepsec->>_tempfile: NamedTempFile::new_in(&workspace) - opt via map_err - visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;cannot final…) - end - opt fs::symlink_metadata(&config).is_ok_and(| m |!m.is_f… - visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;configuratio…) - Note over visioncraft__deepsec: return Err(error(78, #quot;configuration path is not an ordi… - end - visioncraft__deepsec->>_serde_json: serde_json::to_string_pretty(&config_value) - opt via map_err - visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;configuratio…) - end - visioncraft__deepsec->>_tempfile: NamedTempFile::new_in(&workspace) - opt via map_err - visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;cannot final…) - end opt closure + visioncraft__deepsec->>_recorded: recorded::refuse_tracked_workspace(&attempt, &root)? + visioncraft__deepsec->>_tempfile: NamedTempFile::new_in(&workspace) + opt via map_err + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;cannot final…) + end + opt fs::symlink_metadata(&config).is_ok_and(| m |!m.is_f… + visioncraft__deepsec->>visioncraft__deepsec: error(78, #quot;configuratio…) + Note over visioncraft__deepsec: return Err(error(78, #quot;configuration path is not an ordi… + end + visioncraft__deepsec->>_serde_json: serde_json::to_string_pretty(&config_value) + opt via map_err + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;configuratio…) + end + visioncraft__deepsec->>_tempfile: NamedTempFile::new_in(&workspace) + opt via map_err + visioncraft__deepsec->>visioncraft__deepsec: error(70, #quot;cannot final…) + end visioncraft__deepsec->>visioncraft__deepsec___tAttempt: command(#quot;version#quot;, #quot;deepsec#quot;, _, &workspace, false, fal…? visioncraft__deepsec->>visioncraft__deepsec: supported_version() opt rc != 0 || version_text != supported_version() @@ -316,8 +344,8 @@ sequenceDiagram Note over visioncraft__deepsec: return Err(error(78, #quot;Deepsec version does not match th… end visioncraft__deepsec->>visioncraft__deepsec___tAttempt: command(#quot;revision#quot;, #quot;git#quot;, _, &root, false, false)? - visioncraft__deepsec->>visioncraft__deepsec___tAttempt: command(#quot;dirty#quot;, #quot;git#quot;, _, &root, false, false)? visioncraft__deepsec->>_recorded: recorded::select(options, as_deref(), &attempt, &root)? + visioncraft__deepsec->>_recorded: recorded::selected_dirty(&attempt, &root, &selected)? visioncraft__deepsec->>_recorded: recorded::snapshot(&root, &selected)? visioncraft__deepsec->>_serde_json: serde_json::to_vec_pretty(&before) opt via map_err diff --git a/docs/diagrams/generated/src/deepsec_evidence.rs.md b/docs/diagrams/generated/src/deepsec_evidence.rs.md index 54c4288..efd1136 100644 --- a/docs/diagrams/generated/src/deepsec_evidence.rs.md +++ b/docs/diagrams/generated/src/deepsec_evidence.rs.md @@ -3,9 +3,9 @@ sealmap: 2 source: src/deepsec_evidence.rs module: "sym:cargo visioncraft . deepsec_evidence/" language: rust -source_hash: blake3:f26a627cb792b2b78f7637d38ad80a0e0260b566505bedf92cd524d64dd5a0ac -lines: 317 -fragments: 6 +source_hash: blake3:0a9c380830ef2a7ac2da136735a50063ee9ef39345e526537439147442e2cfc6 +lines: 459 +fragments: 9 --- # `sym:cargo visioncraft . deepsec_evidence/` · src/deepsec_evidence.rs > Private checks against the pinned reviewer's persisted protocol. @@ -17,8 +17,10 @@ classDiagram class visioncraft__deepsec_evidence["visioncraft::deepsec_evidence"] { <> #pending(super) Result#lt;Vec#lt;Artifact#gt;, GateError#gt; + #refuse_tracked_workspace(super) Result#lt;#40;#41;, GateError#gt; #run_files(super) Result#lt;BTreeSet#lt;String#gt;, GateError#gt; #select(super) Result#lt;Vec#lt;String#gt;, GateError#gt; + #selected_dirty(super) Result#lt;bool, GateError#gt; #snapshot(super) Result#lt;Vec#lt;Artifact#gt;, GateError#gt; #validate_review(super) Result#lt;Value, GateError#gt; } @@ -89,8 +91,80 @@ sequenceDiagram end ``` +## `sym:cargo visioncraft . deepsec_evidence/tree().` +`fn tree(attempt: &mut Attempt<'_>, root: &Path, reference: &str,) -> Result, GateError>` · L74-L89 +```mermaid +sequenceDiagram + participant visioncraft__deepsec_evidence as deepsec_evidence mod + participant _visioncraft as visioncraft ext + participant visioncraft__git_metadata as git_metadata mod + opt reference.starts_with('-') + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;diff referen…) + Note over visioncraft__deepsec_evidence: return Err(error(78, #quot;diff reference must not be a Git … + end + visioncraft__deepsec_evidence->>visioncraft__git_metadata: git_metadata::tree_arguments(reference, &_) + visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: git_bytes(attempt, root, #quot;reference-tr…, tree_arguments…? + visioncraft__deepsec_evidence->>visioncraft__git_metadata: git_metadata::tree_entries(&bytes) + opt via map_err + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, message) + end +``` + +## `sym:cargo visioncraft . deepsec_evidence/working_hashes().` +`fn working_hashes(attempt: &mut Attempt<'_>, root: &Path, paths: &[String],) -> Result, GateError>` · L109-L153 +```mermaid +sequenceDiagram + participant visioncraft__deepsec_evidence as deepsec_evidence mod + participant _visioncraft as visioncraft ext + participant visioncraft__git_metadata as git_metadata mod + opt paths.len()> 100_000 + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;review file …) + Note over visioncraft__deepsec_evidence: return Err(error(78, #quot;review file count exceeds 100000#quot;… + end + loop for chunk in paths.chunks(64) + loop for name in chunk + opt via map_err + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;source exist…) + end + visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: confined(root, name)? + opt via map_err + visioncraft__deepsec_evidence->>_visioncraft: ~error(70, #quot;source metad…) + end + opt !meta.is_file() || meta.len()> 32 * 1024 * 1024 + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;raw review i…) + Note over visioncraft__deepsec_evidence: return Err(error(78, #quot;raw review input must be an ordin… + end + end + visioncraft__deepsec_evidence->>visioncraft__git_metadata: git_metadata::raw_hash_arguments(&present) + visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: git_bytes(attempt, root, #quot;raw-working-…, raw_hash_argum…? + visioncraft__deepsec_evidence->>visioncraft__git_metadata: git_metadata::raw_hashes(&present, &bytes) + opt via map_err + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, message) + end + end +``` + +## `sym:cargo visioncraft . deepsec_evidence/selected_dirty().` +`pub(super) fn selected_dirty(attempt: &mut Attempt<'_>, root: &Path, paths: &[String],) -> Result` · L178-L200 +> Observe only the selected raw input bytes against their committed Git blobs. +```mermaid +sequenceDiagram + participant visioncraft__deepsec_evidence as deepsec_evidence mod + participant visioncraft__git_metadata as git_metadata mod + participant _visioncraft as visioncraft ext + loop for chunk in paths.chunks(64) + visioncraft__deepsec_evidence->>visioncraft__git_metadata: git_metadata::tree_arguments(#quot;HEAD#quot;, chunk) + visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: git_bytes(attempt, root, #quot;selected-ref…, tree_arguments…? + visioncraft__deepsec_evidence->>visioncraft__git_metadata: git_metadata::tree_entries(&bytes) + opt via map_err + visioncraft__deepsec_evidence->>_visioncraft: ~error(78, message) + end + end + visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: working_hashes(attempt, root, paths)? +``` + ## `sym:cargo visioncraft . deepsec_evidence/select().` -`pub(super) fn select(options: &DeepsecOptions, files: Option<&Path>, attempt: &mut Attempt<'_>, root: &Path,) -> Result, GateError>` · L61-L169 +`pub(super) fn select(options: &DeepsecOptions, files: Option<&Path>, attempt: &mut Attempt<'_>, root: &Path,) -> Result, GateError>` · L202-L311 ```mermaid sequenceDiagram participant visioncraft__deepsec_evidence as deepsec_evidence mod @@ -105,16 +179,15 @@ sequenceDiagram visioncraft__deepsec_evidence->>_visioncraft: ~read_bounded(files, _)? end else - opt let Some(reference) = &options.diff - opt reference.starts_with('-') - visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;diff referen…) - Note over visioncraft__deepsec_evidence: return Err(error(78, #quot;diff reference must not be a Git … + alt !args.is_empty() + visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: git_bytes(attempt, root, #quot;source-selec…, args)? + else + visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: tree(attempt, root, unwrap_or())? + visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: index(attempt, root)? + opt not options.diff_staged + visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: working_hashes(attempt, root, &paths)? end end - opt rc != 0 - visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;could not re…) - Note over visioncraft__deepsec_evidence: return Err(error(78, #quot;could not resolve review source s… - end opt options.diff_working opt rc != 0 visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;could not re…) @@ -133,10 +206,9 @@ sequenceDiagram visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: confined(root, path)? end opt options.diff_staged - opt via map_err - visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;Git paths mu…) - end - opt rc != 0 || changed.split('\0').any(| p | paths.conta… + visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: index(attempt, root)? + visioncraft__deepsec_evidence->>visioncraft__deepsec_evidence: working_hashes(attempt, root, &selected)? + opt paths.iter().any(| p | indexed.get(p).map(| e | &e.o… visioncraft__deepsec_evidence->>_visioncraft: ~error(78, #quot;staged input…) Note over visioncraft__deepsec_evidence: return Err(error(78, #quot;staged inputs differ from working… end @@ -144,7 +216,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . deepsec_evidence/run_files().` -`pub(super) fn run_files(data: &Path) -> Result, GateError>` · L170-L193 +`pub(super) fn run_files(data: &Path) -> Result, GateError>` · L312-L335 ```mermaid sequenceDiagram participant visioncraft__deepsec_evidence as deepsec_evidence mod @@ -174,7 +246,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . deepsec_evidence/validate_review().` -`pub(super) fn validate_review(data: &Path, prior: &BTreeSet, expected: &[Artifact], root: &Path, project: &str, report: &Path,) -> Result` · L220-L317 +`pub(super) fn validate_review(data: &Path, prior: &BTreeSet, expected: &[Artifact], root: &Path, project: &str, report: &Path,) -> Result` · L362-L459 ```mermaid sequenceDiagram participant visioncraft__deepsec_evidence as deepsec_evidence mod diff --git a/docs/diagrams/generated/src/evaluate.rs.md b/docs/diagrams/generated/src/evaluate.rs.md index e13a8ca..f36f577 100644 --- a/docs/diagrams/generated/src/evaluate.rs.md +++ b/docs/diagrams/generated/src/evaluate.rs.md @@ -3,8 +3,8 @@ sealmap: 2 source: src/evaluate.rs module: "sym:cargo visioncraft . evaluate/" language: rust -source_hash: blake3:68c30067ced8712ddcf6cb6c32ff742f62c952f39d3d4fa57951fe599b7da94c -lines: 657 +source_hash: blake3:1950321301950506d38ec7deb1bfe79f0a16099c9d90b833356be23f7f90556d +lines: 666 fragments: 4 --- # `sym:cargo visioncraft . evaluate/` · src/evaluate.rs @@ -172,12 +172,14 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . evaluate/assessment_binding().` -`fn assessment_binding(plan: &QualityPlan, digest: &str, subject: &Subject, claimed: &str, artifact: &crate::Artifact, at: u64, context: &EvaluationContext<'_>,) -> Result<(), ContractError>` · L298-L320 +`fn assessment_binding(plan: &QualityPlan, digest: &str, subject: &Subject, claimed: &str, artifact: &crate::Artifact, at: u64, context: &EvaluationContext<'_>,) -> Result<(), ContractError>` · L298-L324 ```mermaid sequenceDiagram participant visioncraft__evaluate as evaluate mod participant visioncraft as visioncraft mod visioncraft__evaluate->>visioncraft: crate::require(_, #quot;assessment p…)? + visioncraft__evaluate->>visioncraft__evaluate: context_limits(plan, context) + visioncraft__evaluate->>visioncraft: crate::require(is_empty(), #quot;assessment n…)? visioncraft__evaluate->>visioncraft: artifact_shape(artifact)? visioncraft__evaluate->>visioncraft: crate::require(contains(), #quot;assessment a…)? visioncraft__evaluate->>visioncraft__evaluate: age_limit(at, plan, context) @@ -185,7 +187,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . evaluate/expectation_report().` -`fn expectation_report(plan: &QualityPlan, digest: &str, expectation: &Expectation, checks: &[CheckReport], runs: &BTreeMap<&str, &ExecutionReceipt>, context: &EvaluationContext<'_>,) -> ExpectationRe…` · L322-L524 +`fn expectation_report(plan: &QualityPlan, digest: &str, expectation: &Expectation, checks: &[CheckReport], runs: &BTreeMap<&str, &ExecutionReceipt>, context: &EvaluationContext<'_>,) -> ExpectationRe…` · L326-L528 ```mermaid sequenceDiagram participant visioncraft__evaluate as evaluate mod diff --git a/docs/diagrams/generated/src/git_metadata.rs.md b/docs/diagrams/generated/src/git_metadata.rs.md index 8d62f15..e9a8b2e 100644 --- a/docs/diagrams/generated/src/git_metadata.rs.md +++ b/docs/diagrams/generated/src/git_metadata.rs.md @@ -3,8 +3,8 @@ sealmap: 2 source: src/git_metadata.rs module: "sym:cargo visioncraft . git_metadata/" language: rust -source_hash: blake3:36f06c2d0b9d416dc106fd7d20839a5fc424fa52dc1e40f572a1acb24050a467 -lines: 30 +source_hash: blake3:5180f0e3dc3c8f0caf13e2dd1a6ab29b1799760491ce380efcc91c012988c0ae +lines: 142 fragments: 1 --- # `sym:cargo visioncraft . git_metadata/` · src/git_metadata.rs @@ -14,9 +14,20 @@ fragments: 1 ```mermaid classDiagram direction LR + class visioncraft__git_metadata___tEntry["Entry"] { + <> + +mode: String + +object: String + } class visioncraft__git_metadata["visioncraft::git_metadata"] { <> ~fixed_environment(crate) BTreeMap#lt;String, String#gt; + ~index_entries(crate) Result#lt;BTreeMap#lt;String, Entry#gt;, &'static str#gt; ~prefix(crate) Vec#lt;String#gt; + ~raw_hash_arguments(crate) Vec#lt;String#gt; + ~raw_hashes(crate) Result#lt;BTreeMap#lt;String, String#gt;, &'static str#gt; + ~tree_arguments(crate) Vec#lt;String#gt; + ~tree_entries(crate) Result#lt;BTreeMap#lt;String, Entry#gt;, &'static str#gt; } + visioncraft__git_metadata ..> visioncraft__git_metadata___tEntry ``` diff --git a/docs/diagrams/generated/src/process.rs.md b/docs/diagrams/generated/src/process.rs.md index 9836e32..8efa728 100644 --- a/docs/diagrams/generated/src/process.rs.md +++ b/docs/diagrams/generated/src/process.rs.md @@ -3,8 +3,8 @@ sealmap: 2 source: src/process.rs module: "sym:cargo visioncraft . process/" language: rust -source_hash: blake3:aba99dafa4cb40a2a286eaa16908067cf850cba5953360fec3b16569bfff0d28 -lines: 727 +source_hash: blake3:3653d7e09689bd761ffeff3e445975bfa935814efde0ebb6aa9c1ce2adcd903b +lines: 841 fragments: 7 --- # `sym:cargo visioncraft . process/` · src/process.rs @@ -51,7 +51,7 @@ classDiagram ``` ## `sym:cargo visioncraft . process/group_running().` -`fn group_running(pid: u32, deadline: Instant) -> io::Result` · L205-L227 +`fn group_running(pid: u32, deadline: Instant) -> io::Result` · L305-L318 ```mermaid sequenceDiagram participant visioncraft__process as process mod @@ -67,7 +67,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . process/linux_proc/no_longer_member().` -`fn no_longer_member(pid: u32, group: i32) -> io::Result` · L330-L338 +`fn no_longer_member(pid: u32, group: i32) -> io::Result` · L421-L429 ```mermaid sequenceDiagram participant visioncraft__process__linux_proc as linux_proc mod @@ -84,7 +84,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . process/linux_proc/tasks_dead().` -`fn tasks_dead(process: &Path, group: i32, deadline: Instant) -> io::Result` · L340-L360 +`fn tasks_dead(process: &Path, group: i32, deadline: Instant) -> io::Result` · L431-L451 ```mermaid sequenceDiagram participant visioncraft__process__linux_proc as linux_proc mod @@ -109,7 +109,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . process/linux_proc/dead_members().` -`fn dead_members(group: i32, deadline: Instant) -> io::Result>>` · L362-L396 +`fn dead_members(group: i32, deadline: Instant) -> io::Result>>` · L453-L487 ```mermaid sequenceDiagram participant visioncraft__process__linux_proc as linux_proc mod @@ -139,7 +139,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . process/linux_proc/group_running().` -`pub(super) fn group_running(group: i32, deadline: Instant) -> io::Result` · L398-L430 +`pub(super) fn group_running(group: i32, deadline: Instant) -> io::Result` · L489-L521 ```mermaid sequenceDiagram participant visioncraft__process__linux_proc as linux_proc mod @@ -178,7 +178,7 @@ sequenceDiagram ``` ## `sym:cargo visioncraft . process/run_command_with_env().` -`pub(crate) fn run_command_with_env(invocation: &Invocation, root: &Path, output: &Path, cancelled: &AtomicBool, inherit_stdin: bool, overrides: &std::collections::BTreeMap,) -> io::Re…` · L518-L727 +`pub(crate) fn run_command_with_env(invocation: &Invocation, root: &Path, output: &Path, cancelled: &AtomicBool, inherit_stdin: bool, overrides: &std::collections::BTreeMap,) -> io::Re…` · L613-L841 ```mermaid sequenceDiagram participant visioncraft__process as process mod @@ -199,12 +199,20 @@ sequenceDiagram end visioncraft__process->>visioncraft__process: capture(expect(), stdout_file, clone(), clone(), clone(… visioncraft__process->>visioncraft__process: capture(expect(), stderr_file, total, clone(), clone(),… + loop loop + visioncraft__process->>visioncraft__process: leader_exited(&child) + end opt result.termination == Termination::Completed visioncraft__process->>visioncraft__process: group_running(pid, _) end opt result.termination != Termination::Completed - visioncraft__process->>visioncraft__process: signal_group(pid, SIGINT) - visioncraft__process->>visioncraft__process: signal_group(pid, SIGKILL) + visioncraft__process->>visioncraft__process: signal_owned_group(&child, SIGINT) + loop while owns_child && grace.elapsed()>visioncraft__process: leader_exited(&child) + end + end + visioncraft__process->>visioncraft__process: signal_owned_group(&child, SIGKILL) end visioncraft__process->>visioncraft__process: unix_now() ```