From 81ba291c56ba63148c49bd8ddfa848d356d2ae74 Mon Sep 17 00:00:00 2001 From: Transaction Science Date: Tue, 20 Oct 2026 13:51:38 -0400 Subject: [PATCH] joule-code-conformance: the header undersold the harness by a whole suite MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Found while hand-checking a candidate my own cross-standard audit had flagged. The audit was wrong — `verify_cascade` and `verify_gated_cascade` both exist, so C4 and C5 are implemented — but reading the crate to disprove the flag turned up three stale claims in its own documentation. **It says four suites; there are five.** "runs the four suites: C1 content addressing, C2 signing, C3 receipt, C4 cascade" omits C5 gated cascade, whose six vectors demonstrably run (`c5-ungranted-l4-denied-even-when-it-would-close` and friends). A reader of the header would not know C5 is covered at all. This is the understating direction of the same defect the last few changes here have been about: documentation narrower than the code. **It implies something is outstanding when nothing is.** Both the lib header and `main.rs` explain SKIP as "derived fields pending regeneration", while `conformance/v1/regeneration.md` says "Status: all fields are real ... all vectors pass, none skipped. There are no placeholders." The run agrees: 24 passed, 0 failed, 0 skipped. The SKIP mechanism is kept, because a future input change re-opens that state — but it no longer reads as a backlog. All three documents now say the same thing. **And three `cargo doc` warnings were the docs' own fault.** `issuer key = [1;32], agent key = [2;32], steward key = [7;32]` are Rust array literals for the fixed test keys, written without backticks, so rustdoc parsed each as an intra-doc link and could not resolve it. Backticked; `cargo doc --no-deps` for this crate goes from 3 warnings to 0. Verified: pack 24 passed / 0 failed / 0 skipped, tests pass, clippy `-D warnings` clean, `cargo doc` clean. Co-Authored-By: Claude Opus 5 --- .../crates/joule-code-conformance/src/lib.rs | 21 ++++++++++++------- .../crates/joule-code-conformance/src/main.rs | 5 +++-- 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/joule-code/joule-code-rs/crates/joule-code-conformance/src/lib.rs b/joule-code/joule-code-rs/crates/joule-code-conformance/src/lib.rs index 57392cc3b..272a46abd 100644 --- a/joule-code/joule-code-rs/crates/joule-code-conformance/src/lib.rs +++ b/joule-code/joule-code-rs/crates/joule-code-conformance/src/lib.rs @@ -1,12 +1,17 @@ //! Joule Code conformance harness (SPEC §8). //! -//! Loads the published wire vectors and runs the four suites: -//! C1 content addressing, C2 signing, C3 receipt, C4 cascade. Each vector is -//! reported PASS / FAIL / SKIP. SKIP marks a positive crypto vector whose -//! derived field is a placeholder pending regeneration against this library -//! (see `conformance/v1/regeneration.md`); the structural and negative checks, -//! the real Ed25519 known-answer vectors, and the entire cascade suite run for -//! real. Any FAIL makes the run non-zero (CI-ready). +//! Loads the published wire vectors and runs the five suites: C1 content +//! addressing, C2 signing, C3 receipt, C4 cascade, and C5 gated cascade +//! ([`verify_gated_cascade`]). Each vector is reported PASS / FAIL / SKIP, and +//! any FAIL makes the run non-zero (CI-ready). +//! +//! **Nothing is skipped today.** SKIP exists for a positive crypto vector +//! whose derived field is a placeholder pending regeneration against this +//! library, and `conformance/v1/regeneration.md` records that every derived +//! field in the pack is now real — the harness reports 24 passed, 0 failed, +//! 0 skipped. The mechanism is kept because a future input change re-opens +//! that state; what it must not do is read as though something were still +//! outstanding. use std::collections::BTreeMap; use std::path::Path; @@ -454,7 +459,7 @@ impl joule_code_cascade::Stage for Scripted { /// a silent skip). /// /// Fixture constants (third-party implementations must use the same): -/// issuer key = [1;32], agent key = [2;32], steward key = [7;32], +/// issuer key = `[1; 32]`, agent key = `[2; 32]`, steward key = `[7; 32]`, /// steward did = "did:example:joule-code", /// resource = ContentId::of_bytes(b"repo:joule-code"), /// request = { prior: "tree-hash", intent: "rename the function" }, diff --git a/joule-code/joule-code-rs/crates/joule-code-conformance/src/main.rs b/joule-code/joule-code-rs/crates/joule-code-conformance/src/main.rs index 22d04d754..e55cc8fa7 100644 --- a/joule-code/joule-code-rs/crates/joule-code-conformance/src/main.rs +++ b/joule-code/joule-code-rs/crates/joule-code-conformance/src/main.rs @@ -1,8 +1,9 @@ //! `joule-code-conformance` — round-trip the published wire vectors. //! //! Usage: `joule-code-conformance verify ` (e.g. `verify ../conformance/v1`). -//! Exits non-zero if any vector FAILs (CI-ready). SKIPs (derived fields pending -//! regeneration, see `conformance/v1/regeneration.md`) do not fail the run. +//! Exits non-zero if any vector FAILs (CI-ready). A SKIP marks a derived field +//! pending regeneration and does not fail the run; the published pack currently +//! has none (`conformance/v1/regeneration.md`). use std::path::PathBuf; use std::process::ExitCode; -- 2.54.0 (Apple Git-157)