diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..b4862cc --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,37 @@ +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@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.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..45ecbb9 --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,45 @@ +[package] +name = "visioncraft" +version = "0.1.0" +edition = "2024" +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" +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", "fs"], 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/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..9f3936a 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,252 @@ # 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 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. + +## 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.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 +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. + +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 +`--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. +This project dogfoods that workflow in its [verified ADRs and diagrams](docs/diagrams/README.md). + +## 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. 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. 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 +[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 +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/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/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/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/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..3ae6de8 --- /dev/null +++ b/docs/PROVENANCE.md @@ -0,0 +1,95 @@ +# 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. + +## 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 +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/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. diff --git a/docs/REVIEW-2026-11-03.md b/docs/REVIEW-2026-11-03.md new file mode 100644 index 0000000..5019df3 --- /dev/null +++ b/docs/REVIEW-2026-11-03.md @@ -0,0 +1,55 @@ +# 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; 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 +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. + +## 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 new file mode 100644 index 0000000..25b75b0 --- /dev/null +++ b/docs/UPSTREAM-DEEPSEC.md @@ -0,0 +1,149 @@ +# 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. + +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 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 +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 + +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 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. + +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). + +## 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 new file mode 100644 index 0000000..b82e743 --- /dev/null +++ b/docs/ZEROSHOT-LESSONS.md @@ -0,0 +1,88 @@ +# 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. + +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 +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. + +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 +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/docs/adr/0001-portable-quality-contract.md b/docs/adr/0001-portable-quality-contract.md new file mode 100644 index 0000000..df4e602 --- /dev/null +++ b/docs/adr/0001-portable-quality-contract.md @@ -0,0 +1,69 @@ +--- +id: ADR-0001 +title: Portable quality contracts with explicit execution adapters +status: accepted +date: 2026-11-03 +verified_commit: e3306776ebab083a7842b02ce4fec4e0a2bbc77c +verified_paths: + - src/plan.rs + - src/evidence.rs + - src/evaluate.rs + - src/cli.rs + - src/process.rs + - src/git_metadata.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. + +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 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 +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, +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, +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..983ed88 --- /dev/null +++ b/docs/adr/0002-specialist-upstream-boundaries.md @@ -0,0 +1,62 @@ +--- +id: ADR-0002 +title: Consume specialist reviewers through versioned upstream contracts +status: accepted +date: 2026-11-03 +depends_on: [ADR-0001] +verified_commit: e3306776ebab083a7842b02ce4fec4e0a2bbc77c +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 +--- + +# 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..c082bc8 --- /dev/null +++ b/docs/diagrams/README.md @@ -0,0 +1,50 @@ +# 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. 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 \ + --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 +`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 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] + 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..9744fc5 --- /dev/null +++ b/docs/diagrams/generated/_index.json @@ -0,0 +1 @@ +{"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 new file mode 100644 index 0000000..79be895 --- /dev/null +++ b/docs/diagrams/generated/_overview.md @@ -0,0 +1,378 @@ +--- +sealmap: 2 +kind: overview +codebase: visioncraft +--- +# visioncraft overview +10 files · 182 symbols · 691 relations · 90 flows · 583 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"}} + serde{{"serde"}} + serde_json{{"serde_json"}} + sha2{{"sha2"}} + signal_hook{{"signal_hook"}} + tempfile{{"tempfile"}} + url{{"url"}} + visioncraft -->|"4"| Instant + visioncraft -->|"3"| Path + visioncraft -->|"5"| clap + visioncraft -->|"1"| fs + visioncraft -->|"11"| io + visioncraft -->|"32"| nix + visioncraft -->|"7"| recorded + visioncraft -->|"37"| sealmap_corpus + visioncraft -->|"14"| serde + visioncraft -->|"20"| 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__git_metadata["git_metadata"] + 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 -->|"4"| 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 + 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 +``` + +## 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..13a14f5 --- /dev/null +++ b/docs/diagrams/generated/src/cli.rs.md @@ -0,0 +1,563 @@ +--- +sealmap: 2 +source: src/cli.rs +module: "sym:cargo visioncraft . cli/" +language: rust +source_hash: blake3:88c24a1ad87b7d1fdf86ccd6ec14585657147358a0f29d10bee5669885c5c451 +lines: 1118 +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` · L225-L251 +```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>` · L273-L285 +```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` · L287-L312 +```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>` · L314-L326 +```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` · 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)? + 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` · L407-L417 +```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` · 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 + 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 + 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>` · L476-L504 +```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>` · L506-L540 +```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` · L547-L635 +```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>` · L637-L645 +```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` · L657-L668 +```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() && !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` · L742-L898 +```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>` · L900-L930 +```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` · L932-L1077 +```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 + 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)? + 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.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 + 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->>_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` · L1079-L1118 +> 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..33694c3 --- /dev/null +++ b/docs/diagrams/generated/src/deepsec.rs.md @@ -0,0 +1,412 @@ +--- +sealmap: 2 +source: src/deepsec.rs +module: "sym:cargo visioncraft . deepsec/" +language: rust +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. + +## 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-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) + 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_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) + 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/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` · L640-L1046 +> 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 _recorded as recorded ext + participant _tempfile as tempfile ext + participant visioncraft__deepsec___tAttempt as Attempt + 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)? + 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;)) + 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 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() + 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->>_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 + 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..efd1136 --- /dev/null +++ b/docs/diagrams/generated/src/deepsec_evidence.rs.md @@ -0,0 +1,306 @@ +--- +sealmap: 2 +source: src/deepsec_evidence.rs +module: "sym:cargo visioncraft . deepsec_evidence/" +language: rust +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. + +## structure +```mermaid +classDiagram + direction LR + 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; + } + 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/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>` · L202-L311 +```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 + 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 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 + 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 + end +``` + +## `sym:cargo visioncraft . deepsec_evidence/run_files().` +`pub(super) fn run_files(data: &Path) -> Result, GateError>` · L312-L335 +```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` · L362-L459 +```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..f36f577 --- /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:1950321301950506d38ec7deb1bfe79f0a16099c9d90b833356be23f7f90556d +lines: 666 +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 &… + 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… + 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-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) + 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…` · L326-L528 +```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/git_metadata.rs.md b/docs/diagrams/generated/src/git_metadata.rs.md new file mode 100644 index 0000000..e9a8b2e --- /dev/null +++ b/docs/diagrams/generated/src/git_metadata.rs.md @@ -0,0 +1,33 @@ +--- +sealmap: 2 +source: src/git_metadata.rs +module: "sym:cargo visioncraft . git_metadata/" +language: rust +source_hash: blake3:5180f0e3dc3c8f0caf13e2dd1a6ab29b1799760491ce380efcc91c012988c0ae +lines: 142 +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___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/lib.rs.md b/docs/diagrams/generated/src/lib.rs.md new file mode 100644 index 0000000..625000a --- /dev/null +++ b/docs/diagrams/generated/src/lib.rs.md @@ -0,0 +1,46 @@ +--- +sealmap: 2 +source: src/lib.rs +module: "sym:cargo visioncraft ." +language: rust +source_hash: blake3:bd0cbb39c4723d919330852c9a157a2284d5b8102817d2c74eb7dd89a715bffb +lines: 132 +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; + +mod git_metadata + ~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..d65f670 --- /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:4bb59bf863aec89c7e0f6ea0dc232c477e58b0d54775b003a29d43b892e22326 +lines: 39 +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..8efa728 --- /dev/null +++ b/docs/diagrams/generated/src/process.rs.md @@ -0,0 +1,218 @@ +--- +sealmap: 2 +source: src/process.rs +module: "sym:cargo visioncraft . process/" +language: rust +source_hash: blake3:3653d7e09689bd761ffeff3e445975bfa935814efde0ebb6aa9c1ce2adcd903b +lines: 841 +fragments: 7 +--- +# `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/group_running().` +`fn group_running(pid: u32, deadline: Instant) -> io::Result` · L305-L318 +```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` · L421-L429 +```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` · L431-L451 +```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>>` · L453-L487 +```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` · L489-L521 +```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…` · L613-L841 +```mermaid +sequenceDiagram + participant visioncraft__process as process mod + participant visioncraft__plan___tInvocation as Invocation + 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(),… + 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_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() +``` 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/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/skills/visioncraft/SKILL.md b/skills/visioncraft/SKILL.md new file mode 100644 index 0000000..821535a --- /dev/null +++ b/skills/visioncraft/SKILL.md @@ -0,0 +1,122 @@ +--- +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) | +| 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) | + +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..9d869d2 --- /dev/null +++ b/skills/visioncraft/assets/provenance.json @@ -0,0 +1,415 @@ +{ + "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/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", + "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/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", + "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", + "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", + "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" + ] + } + ], + "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/agentic-qe.md b/skills/visioncraft/references/agentic-qe.md new file mode 100644 index 0000000..962bf85 --- /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 new file mode 100644 index 0000000..73a0b0a --- /dev/null +++ b/skills/visioncraft/references/architecture.md @@ -0,0 +1,70 @@ +# 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 + +[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 +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..f42af01 --- /dev/null +++ b/skills/visioncraft/references/deepsec.md @@ -0,0 +1,95 @@ +# 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. + +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, +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. + +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. +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..0b6d067 --- /dev/null +++ b/skills/visioncraft/references/ecosystem-agentbox.md @@ -0,0 +1,86 @@ +# 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. + +## 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 +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..5963607 --- /dev/null +++ b/skills/visioncraft/references/quality-gates.md @@ -0,0 +1,102 @@ +# 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 + +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 +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. + +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 +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 +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..cfda2b2 --- /dev/null +++ b/skills/visioncraft/references/review-evidence.md @@ -0,0 +1,189 @@ +# 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. + +## 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 +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. + +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. +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..db41a28 --- /dev/null +++ b/skills/visioncraft/references/worked-examples.md @@ -0,0 +1,167 @@ +# 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. + +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 +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. diff --git a/src/cli.rs b/src/cli.rs new file mode 100644 index 0000000..5e4f8ca --- /dev/null +++ b/src/cli.rs @@ -0,0 +1,1118 @@ +//! 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. +//! 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}; +use std::io::{Read, Write}; +use std::path::{Component, Path, PathBuf}; +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(Box), + /// 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, + /// Caller-declared component label; defaults to the root directory name. + #[arg(long)] + repository: Option, + /// Caller-declared features/target/fixture label, not an observed digest. + #[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, + /// 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. + #[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) +} + +struct GitOutput { + success: bool, + stdout: Vec, +} + +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 = crate::git_metadata::prefix(); + argv.push("-C".into()); + 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 = crate::git_metadata::fixed_environment(); + 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.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], cancelled: &AtomicBool) -> Result { + // Git status/diff may invoke configured clean filters. Compare unfiltered + // committed blob bytes instead; worktree conversion differences are dirty. + 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 entries = + crate::git_metadata::tree_entries(&output.stdout).map_err(|message| error(70, message))?; + for path in paths { + 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")); + } + 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 committed_hash != crate::sha256(¤t) { + 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, cancelled: &AtomicBool) -> 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, cancelled)?; + let selected = inputs(&root, &paths, false)?; + let dirty = selected_dirty(&root, &paths, cancelled)?; + 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() + && !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 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)?; + 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, cancelled)? != 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, cancelled)? != 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 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(&actual_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: 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, + 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, 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, 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() { + return Err(error( + 1, + "all selected source inputs are missing; evidence is stale", + )); + } + current.dirty = selected_dirty(&source_root, &paths, cancelled)?; + 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.revision != current.revision + || supplied.inputs != current.inputs + || supplied.dirty != current.dirty + { + return Err(error( + 2, + "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(); + 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, + ], + cancelled, + )? + .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); + let label_basis = if options.current_subject.is_some() { + "caller-attested" + } else { + "plan-declared-unverified" + }; + if options.json { + 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)", + report.outcome, + report.passed_required_checks, + 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!( + "{}: {:?} — {}", + 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, cancelled), + 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, cancelled), + Operation::Deepsec(options) => { + crate::deepsec::execute(&options, cancelled).map_err(|e| error(e.code, e.message)) + } + } +} diff --git a/src/deepsec.rs b/src/deepsec.rs new file mode 100644 index 0000000..acb646d --- /dev/null +++ b/src/deepsec.rs @@ -0,0 +1,1084 @@ +//! 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 [`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_with_env}; +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; + +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); + +/// 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 the repository and process its pending candidates. + #[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 (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, + 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_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() + .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")) +} + +#[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 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()) + || (meta.is_file() && meta.nlink() != 1) + { + return Err(error( + 78, + "review workspace contains redirected or special entries", + )); + } + 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)); + } + } + } + Ok(()) +} + +/// 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(all(target_os = "linux", not(target_env = "uclibc"))))] + { + let _ = (options, cancelled); + Err(error(78, "Deepsec process adapter requires Linux")) + } + #[cfg(all(target_os = "linux", not(target_env = "uclibc")))] + { + 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":supported_version(),"deepsec_protocol_version":PROTOCOL["adapter_protocol_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)?; + validate_workspace_tree(&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"))?, + )?; + 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 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", + vec!["--version".into()], + &workspace, + false, + false, + )?; + let version_text = String::from_utf8_lossy(&version) + .trim() + .trim_start_matches("deepsec ") + .to_owned(); + // Store only the bounded version token, never arbitrary subprocess output. + if version_text.len() <= 64 + && version_text + .bytes() + .all(|b| b.is_ascii_alphanumeric() || b".+-_".contains(&b)) + { + observed_version = Some(version_text.clone()); + } + if rc != 0 || version_text != supported_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 selected = recorded::select(options, files.as_deref(), &mut attempt, &root)?; + dirty = Some(recorded::selected_dirty(&mut attempt, &root, &selected)?); + 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":observed_version,"deepsec_version_required":supported_version(),"deepsec_git_head":PROTOCOL["package"]["git_head"],"deepsec_npm_integrity":PROTOCOL["package"]["integrity"],"deepsec_protocol_version":PROTOCOL["adapter_protocol_version"],"release_identity_boundary":"Expected upstream identity; installed package bytes are verified by the host. CLI version was observed separately.","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()); + object.insert( + "dirty_scope".into(), + Value::String("selected-inputs".into()), + ); + 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 policy = DeepsecPolicy { + ai_base_url: "https://user:password@example.com".into(), + ..DeepsecPolicy::default() + }; + 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..803e477 --- /dev/null +++ b/src/deepsec_evidence.rs @@ -0,0 +1,459 @@ +//! 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() +} +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>, + 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 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::new() + }; + 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); + } + out + }; + 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 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", + )); + } + } + 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() + && 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); + } + } + let records: BTreeMap<_, _> = 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")); + } + 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", + )); + } + for artifact in expected { + let record = &records[&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_none_or(|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", + )); + } + } + 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/evaluate.rs b/src/evaluate.rs new file mode 100644 index 0000000..acd2798 --- /dev/null +++ b/src/evaluate.rs @@ -0,0 +1,666 @@ +//! 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"); + } + let mut output_bytes = 0u64; + for output in receipt.stdout.iter().chain(receipt.stderr.iter()) { + 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 + && !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", + )?; + 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), + "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 + || context + .audits + .iter() + .any(|a| a.expectation_id == expectation.id) + { + 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 + && r.finished_at_ms <= a.captured_at_ms + }) + }), + "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 + && 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 + || (a.verdict == AuditVerdict::Contradicted + && c.outcome == CheckOutcome::Blocked)) + }), + "adversarial probe did not complete successfully", + )?; + 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( + 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()); + } + 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 + || context + .manual_observations + .iter() + .any(|m| m.expectation_id == expectation.id) + { + 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. +/// +/// 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], + 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 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) + && (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 + .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..fd04a48 --- /dev/null +++ b/src/evidence.rs @@ -0,0 +1,292 @@ +//! Immutable run and audit records, with caller-supplied byte verification. + +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::{BTreeMap, 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. + /// 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>, + /// 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_input_paths(&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: BTreeMap<(String, String), u64>, +} + +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()), + 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_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/git_metadata.rs b/src/git_metadata.rs new file mode 100644 index 0000000..80c0522 --- /dev/null +++ b/src/git_metadata.rs @@ -0,0 +1,142 @@ +//! 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", + "--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 new file mode 100644 index 0000000..a74c076 --- /dev/null +++ b/src/lib.rs @@ -0,0 +1,132 @@ +//! 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() +} + +/// 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; + +/// 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 new file mode 100644 index 0000000..29c24cd --- /dev/null +++ b/src/main.rs @@ -0,0 +1,39 @@ +//! 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_os().nth(1).as_deref() == Some(std::ffi::OsStr::new("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/src/plan.rs b/src/plan.rs new file mode 100644 index 0000000..82ad4ca --- /dev/null +++ b/src/plan.rs @@ -0,0 +1,413 @@ +//! 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; + +/// 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)] +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")?; + 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)?; + 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. 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, + /// 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. + /// + /// # 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()?; + 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( + self.checks.len() <= MAX_PLAN_CHECKS, + "plan check count exceeds admission ceiling", + )?; + 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(); + 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 { + 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() + || (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", + )?; + 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)) + } +} diff --git a/src/process.rs b/src/process.rs new file mode 100644 index 0000000..671fa6f --- /dev/null +++ b/src/process.rs @@ -0,0 +1,841 @@ +//! 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; +#[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; +#[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. +#[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, +} + +#[cfg(all(target_os = "linux", not(target_env = "uclibc")))] +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(all(target_os = "linux", not(target_env = "uclibc")))] +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(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)? + { + 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(all(target_os = "linux", not(target_env = "uclibc")))] +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(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; + 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); + } + // Signal 0 proves existence, not execution: zombies still occupy groups. + linux_proc::group_running(group, deadline) +} + +#[cfg(all(target_os = "linux", not(target_env = "uclibc")))] +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()); + } + } +} + +/// 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 -`. +/// +/// 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. 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, + 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(all(target_os = "linux", not(target_env = "uclibc"))))] + { + let _ = ( + invocation, + root, + output, + cancelled, + inherit_stdin, + overrides, + ); + Err(io::Error::new( + io::ErrorKind::Unsupported, + "bounded execution requires Linux with supported non-reaping child observation", + )) + } + #[cfg(all(target_os = "linux", not(target_env = "uclibc")))] + { + 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") + })?; + 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); + } + } + command.envs(overrides); + 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 exited = false; + let mut owns_child = true; + 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 leader_exited(&mut child) { + Ok(true) => { + exited = true; + break Termination::Completed; + } + Ok(false) => thread::sleep(Duration::from_millis(10)), + Err(_) => { + owns_child = false; + 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. + 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) { + 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 { + 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 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() && exited { + break; + } + thread::sleep(Duration::from_millis(10)); + } + 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() { + 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(()))) { + 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/core.rs b/tests/core.rs new file mode 100644 index 0000000..e0f6820 --- /dev/null +++ b/tests/core.rs @@ -0,0 +1,755 @@ +//! 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.policy.max_age_ms = None; + 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; + 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] +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()); +} + +#[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 new file mode 100644 index 0000000..17da76e --- /dev/null +++ b/tests/deepsec.rs @@ -0,0 +1,429 @@ +//! External reviewer protocol controls using a model-free executable double. +#![cfg(all(target_os = "linux", not(target_env = "uclibc"), feature = "cli"))] +use serde_json::{Value, json}; +use std::fs; +use std::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 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 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; + 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 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 [ + "runtime", + "no-evidence", + "incomplete", + "refused", + "partial", + "unknown-refusal", + "missing-skipped", + "null-skipped", + "scalar-skipped", + "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..9aae1a7 --- /dev/null +++ b/tests/fixtures/deepsec.py @@ -0,0 +1,55 @@ +#!/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,'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'] + 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/native_cli.rs b/tests/native_cli.rs new file mode 100644 index 0000000..dbdca2a --- /dev/null +++ b/tests/native_cli.rs @@ -0,0 +1,771 @@ +//! Executed native CLI contracts using local temporary Git fixtures only. +#![cfg(all(target_os = "linux", not(target_env = "uclibc"), 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 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; + 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()); + 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" + ); + 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()); +} + +#[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()); +} diff --git a/tests/process.rs b/tests/process.rs new file mode 100644 index 0000000..c5f99a6 --- /dev/null +++ b/tests/process.rs @@ -0,0 +1,254 @@ +//! Executable process-boundary controls. +#![cfg(all(target_os = "linux", not(target_env = "uclibc"), 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); +} + +#[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(); + 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"); +} 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()