From 428e81b6b49a04176f4fdf53d1e1d65d20e9ad18 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 14:38:14 +0000 Subject: [PATCH 1/2] fix(evidence): derive reader path candidates by component, as the writer does The writer keys a file with `Path::strip_prefix`, which compares components. The reader removed a literal string prefix. For root `repo` and file `repo/./a.php` the writer keyed `a.php` and the reader derived `./a.php`, so `validate-report` rejected a report this build had written: `semantic fingerprint mismatch` as 0.5.0 and `record/finding mismatch` as its frozen 0.4.0 projection. Repeated separators, a trailing `.`, the root spelling `repo/.` and a file named twice had the same defect. `path_for_style` now compares components for each reading (the root, then every name; empty components and every `.` except a leading one are dropped; `..` is kept) and returns the producer's spelling from the next component to the end of the last one. `relative_path`, the semantic fingerprint, the single-reading rule in the validator and both schemas are unchanged, so current and frozen keys are unchanged. The lexical `./a.php` is not an extra candidate. Controls: exact POSIX and Windows readings for each case, compared with the native writer on the host that runs them; an exhaustive comparison of the native writer with the host reading over every short path (132,253 pairs on Linux); and a contract test that drives this build's own `scan_files` report through `pons validate-report` as 0.5.0 and 0.4.0, with relative `repo` labels in both separator styles, and rejects the lexical key as record path, fingerprint input, both, and in a frozen report. Validation on x86_64 Linux, rustc 1.97.1: fmt and all-target Clippy with warnings denied passed. As root, 266 tests passed and the three POSIX permission fixtures failed, as they do at 612145d (263 passed, 3 failed); the pons-core unit binary as uid 1000 passed 146 of 146. tests/e2e.sh passed 46 of 46 on the release build. No Windows host ran these tests locally; hosted Linux and Windows checks must complete on the pull request. Drive, UNC and verbatim prefixes remain ordinary names in the reader. Creusot/Pearlite and Verus remain OPEN/not run. Addresses the open review finding on #73 and contributes to hyperpolymath/echo-types#362. Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_0136P7ZmAsYpFA9gxfQLF3F6 Signed-off-by: Claude --- crates/pons-cli/tests/contracts.rs | 101 +++++++++++++++ crates/pons-core/src/evidence.rs | 195 ++++++++++++++++++++++++++--- docs/echo-362-verification.adoc | 65 ++++++++++ 3 files changed, 343 insertions(+), 18 deletions(-) diff --git a/crates/pons-cli/tests/contracts.rs b/crates/pons-cli/tests/contracts.rs index 9f96d25..0111a23 100644 --- a/crates/pons-cli/tests/contracts.rs +++ b/crates/pons-cli/tests/contracts.rs @@ -378,3 +378,104 @@ fn ambiguous_legacy_paths_require_one_consistent_record_and_fingerprint() { ); } } + +/// The writer keys a file by component (`Path::strip_prefix`), so a `.` next to +/// the scan root never reaches a key; the reader has to derive the same one. +/// The report here is this build's own output, not a hand-made document. +#[test] +fn a_component_equivalent_file_spelling_validates_with_the_writer_key() { + use pons_core::{ + corroborate::fingerprint_of, engine::Engine, finding::EvidenceClass, lang::Lang, + source::DiscoveredFile, + }; + fn rebase(value: &mut Value, root: &str, separator: &str) { + match value { + Value::String(text) => { + if let Some(suffix) = text.strip_prefix(root) { + *text = format!("repo{}", suffix.replace(['/', '\\'], separator)); + } + } + Value::Array(values) => values + .iter_mut() + .for_each(|value| rebase(value, root, separator)), + Value::Object(values) => values + .values_mut() + .for_each(|value| rebase(value, root, separator)), + _ => (), + } + } + fn accepted(fixture: &Fixture, report: &Value, what: &str) { + for (version, document) in [("0.5.0", report.clone()), ("0.4.0", as_0_4_0(report))] { + let result = fixture.validate(&document); + assert!( + result.status.success(), + "{what} as {version}: {}", + String::from_utf8_lossy(&result.stderr) + ); + } + } + let fixture = Fixture::new(); + // The CLI makes its root absolute and walks it, so it never names a file + // through a `.` component. The public `scan_files` API can. + let spelled = fixture.src.join(".").join("sample.php"); + let scanned = Engine::new(pons_rules::registry::RuleRegistry::all()).scan_files( + &fixture.src, + &[DiscoveredFile { + path: spelled.clone(), + lang: Lang::Php, + }], + ); + let native: Value = + serde_json::from_str(&pons_core::report::json::render(&scanned).unwrap()).unwrap(); + assert_eq!( + native["findings"][0]["location"]["file"], + json!(spelled.display().to_string()), + "the report must carry the spelling under test" + ); + assert_eq!( + native["evidence_contract"]["records"][0]["path"], + "sample.php" + ); + accepted(&fixture, &native, "the native report"); + + // The same report under a relative root label, in each separator style. + // No writer emits the lexical `./sample.php`: it is refused as a record + // path, as a fingerprint input, as both together, and in a frozen report. + let root = native["scanned"]["root"].as_str().unwrap().to_owned(); + let lexical = "./sample.php"; + for (separator, file) in [("/", "repo/./sample.php"), ("\\", r"repo\.\sample.php")] { + let mut relative = native.clone(); + rebase(&mut relative, &root, separator); + assert_eq!(relative["scanned"]["root"], "repo"); + assert_eq!(relative["findings"][0]["location"]["file"], file); + accepted(&fixture, &relative, file); + + let evidence: EvidenceClass = + serde_json::from_value(relative["findings"][0]["evidence"].clone()).unwrap(); + let line = relative["findings"][0]["location"]["line_start"] + .as_u64() + .unwrap() as usize; + for (record, fingerprint) in [(true, false), (false, true), (true, true)] { + let mut forged = relative.clone(); + if record { + forged["evidence_contract"]["records"][0]["path"] = json!(lexical); + } + if fingerprint { + forged["findings"][0]["semantic_fingerprint"] = + json!(fingerprint_of(lexical, line, evidence)); + } + assert_eq!( + fixture.validate(&forged).status.code(), + Some(2), + "{file}: lexical key accepted (record {record}, fingerprint {fingerprint})" + ); + } + let mut frozen = as_0_4_0(&relative); + frozen["evidence_contract"]["records"][0]["path"] = json!(lexical); + assert_eq!( + fixture.validate(&frozen).status.code(), + Some(2), + "{file}: lexical key accepted in a frozen report" + ); + } +} diff --git a/crates/pons-core/src/evidence.rs b/crates/pons-core/src/evidence.rs index 355981d..1ebbc81 100644 --- a/crates/pons-core/src/evidence.rs +++ b/crates/pons-core/src/evidence.rs @@ -23,28 +23,53 @@ pub(crate) fn relative_path(file: &str, root: &str) -> String { .replace('\\', "/") } +/// The components `std::path` compares, each with its offset in `text`: the +/// root, then every name. Empty components are dropped, and so is every `.` +/// except a leading one; `..` is kept. Only the Windows reading tells a `//` +/// root from `/`. Drive and verbatim prefixes are ordinary names here, as +/// they were under the literal rule this replaces. +fn components(text: &str, windows: bool) -> Vec<(&str, usize)> { + let body = text.trim_start_matches('/'); + let lead = text.len() - body.len(); + let mut parts = Vec::new(); + if lead > 0 { + parts.push((&text[..lead.min(1 + usize::from(windows))], 0)); + } + let mut start = lead; + for name in body.split('/') { + if !name.is_empty() && (name != "." || start == 0) { + parts.push((name, start)); + } + start += name.len() + 1; + } + parts +} + +// One reading of `relative_path`: the same component comparison, and the same +// remainder, without `std::path` and therefore without the reader's host. fn path_for_style(file: &str, root: &str, windows: bool) -> (String, bool) { - let file = if windows { - file.replace('\\', "/") - } else { - file.into() - }; - let root = if windows { - root.replace('\\', "/") + let (file, root) = if windows { + (file.replace('\\', "/"), root.replace('\\', "/")) } else { - root.into() + (file.to_owned(), root.to_owned()) }; - let base = if file == root { - root.rsplit_once('/').map_or("", |(parent, _)| parent) - } else { - root.trim_end_matches('/') - }; - let prefix = format!("{base}/"); - let relative = if base.is_empty() && !file.starts_with('/') { - Some(file.as_str()) - } else { - file.strip_prefix(&prefix) + let parts = components(&file, windows); + let base = components(&root, windows); + let same = |a: &[(&str, usize)], b: &[(&str, usize)]| { + a.iter().map(|part| part.0).eq(b.iter().map(|part| part.0)) }; + // A file that is the root itself is keyed below the root's parent. A bare + // root has no parent. + let has_parent = base.last().is_some_and(|last| !last.0.starts_with('/')); + let depth = base.len() - usize::from(has_parent && same(&parts, &base)); + let relative = (parts.len() >= depth && same(&parts[..depth], &base[..depth])).then(|| { + match (parts.get(depth), parts.last()) { + // As `Components::as_path`: from the next component to the end of + // the last one, spelled as the producer spelled it. + (Some(first), Some(last)) => &file[first.1..last.1 + last.0.len()], + _ => "", + } + }); ( relative.unwrap_or(&file).replace('\\', "/"), relative.is_some(), @@ -119,6 +144,140 @@ mod portable_paths { .any(|(path, _)| path == expected)); } } + // The writer strips by component (`Path::strip_prefix`), so `.` and + // repeated separators next to the root never reach a key. Each row gives + // the exact POSIX and Windows readings; the native writer is compared with + // the reading of the host that runs the test. + #[test] + fn component_equivalent_spellings_have_the_writer_key() { + let inside = |key: &str| (key.to_string(), true); + let outside = |key: &str| (key.to_string(), false); + for (file, root, posix, windows) in [ + ("repo/./a.php", "repo", inside("a.php"), inside("a.php")), + ( + "repo/./sub/a.php", + "repo", + inside("sub/a.php"), + inside("sub/a.php"), + ), + ("repo//a.php", "repo", inside("a.php"), inside("a.php")), + ("repo/a.php/.", "repo", inside("a.php"), inside("a.php")), + ("repo/a.php", "repo/.", inside("a.php"), inside("a.php")), + ("repo/a.php", "repo//", inside("a.php"), inside("a.php")), + // The same file named twice: the key is its name below the parent. + ( + "repo/./a.php", + "repo/a.php", + inside("a.php"), + inside("a.php"), + ), + ("./a.php", ".", inside("a.php"), inside("a.php")), + ( + "/tmp/repo/./a.php", + "/tmp/repo", + inside("a.php"), + inside("a.php"), + ), + // Only the components next to the root are dropped. The remainder + // keeps its spelling, `..` is never resolved, and a leading `.` is + // a component of its own. + ( + "repo/sub/./a.php", + "repo", + inside("sub/./a.php"), + inside("sub/./a.php"), + ), + ( + "repo/../repo/a.php", + "repo", + inside("../repo/a.php"), + inside("../repo/a.php"), + ), + ( + "./repo/a.php", + "repo", + outside("./repo/a.php"), + outside("./repo/a.php"), + ), + // A backslash separates components only in the Windows reading. + ( + r"repo\.\a.php", + "repo", + outside("repo/./a.php"), + inside("a.php"), + ), + ( + r"repo\.\sub\a.php", + r"repo\", + outside("repo/./sub/a.php"), + inside("sub/a.php"), + ), + ] { + let native = if cfg!(windows) { &windows } else { &posix }; + assert_eq!( + super::relative_path(file, root), + native.0, + "writer: {file} in {root}" + ); + let mut expected = vec![posix.clone()]; + // An absolute POSIX root has one reading. + if windows != posix && !root.starts_with('/') { + expected.push(windows); + } + assert_eq!( + path_candidates(file, root), + expected, + "reader: {file} in {root}" + ); + } + assert_eq!( + path_candidates(r"C:\repo\.\a.php", r"C:\repo"), + vec![inside("a.php")] + ); + assert_eq!( + path_candidates(r"//server/share\.\a.php", "//server/share")[1], + inside("a.php") + ); + } + // Every short path over a name, `.` and the host's separators: the reading + // for this host is the native writer, string for string. Windows prefixes + // need `:` or two leading separators; the reader does not model them, so + // they are not generated. + #[test] + fn the_host_reading_is_the_native_writer_on_every_short_path() { + let alphabet: &[char] = if cfg!(windows) { + &['a', '.', '/', '\\'] + } else { + &['a', '.', '/'] + }; + let mut paths = vec![String::new()]; + let mut from = 0; + for _ in 0..6 { + let until = paths.len(); + for index in from..until { + for letter in alphabet { + paths.push(format!("{}{letter}", paths[index])); + } + } + from = until; + } + let prefixed = |path: &str| { + cfg!(windows) && path.len() > 1 && path[..2].chars().all(|c| matches!(c, '/' | '\\')) + }; + paths.retain(|path| !prefixed(path)); + let mut compared = 0usize; + for file in &paths { + for root in paths.iter().filter(|root| root.len() < 5) { + assert_eq!( + super::path_for_style(file, root, cfg!(windows)).0, + super::relative_path(file, root), + "{file:?} in {root:?}" + ); + compared += 1; + } + } + assert!(compared > 100_000, "the comparison was vacuous: {compared}"); + } } #[derive(Debug, Clone, Default, Serialize, Deserialize)] #[serde(deny_unknown_fields)] diff --git a/docs/echo-362-verification.adoc b/docs/echo-362-verification.adoc index b244f52..5143d89 100644 --- a/docs/echo-362-verification.adoc +++ b/docs/echo-362-verification.adoc @@ -111,3 +111,68 @@ This establishes internal consistency, not a unique historical filesystem identity. Tests cover both 0.4.0 and 0.5.0 legacy forms and reject mixed interpretations; the Windows workspace suite passed 261 test executions, with all-target Clippy and the eight CLI contract tests passing. + +== Component-equivalent paths — 10 November 2026 + +The review of #73 left one finding open. The writer and the reader disagreed +on a file named through a component that `std::path` drops. For root `repo` +and file `repo/./a.php`, the writer (`Path::strip_prefix`) keys `a.php`. The +reader removed the literal prefix `repo/` and derived `./a.php`. + +Reproduced at `612145d805c6ec519d60fc65e406e9c091462848` on x86_64 Linux with +rustc 1.97.1 (`8bab26f4f`), the `rust-toolchain.toml` pin: + +* `Engine::scan_files` wrote record path `sample.php` for the file + `/./sample.php`. `pons validate-report` rejected that report with + `semantic fingerprint mismatch` as 0.5.0, and with `record/finding mismatch` + as its frozen 0.4.0 projection. +* The same disagreement occurred for `repo/./sub/a.php`, `repo//a.php`, + `repo/a.php/.`, the root spelling `repo/.`, the absolute form + `/tmp/repo/./a.php`, and one file named twice (file `repo/./a.php`, root + `repo/a.php`). +* Not affected: the root spelling `repo//`, `./a.php` below `.`, and spelling + after the first kept component (`repo/sub/./a.php` is `sub/./a.php` on both + sides). +* The Windows spelling `repo\.\a.php` does not reproduce on a POSIX writer, + which keeps the string as one name. The reader's Windows reading had the + defect (`./a.php`). A Windows writer was not run locally. + +The reader now derives each reading with the writer's rule. It compares +components (the root, then every name; empty components and every `.` except +a leading one are dropped; `..` is kept) and returns the producer's spelling +from the next component to the end of the last one. The writer, the +fingerprint, the validator rule that requires one reading, and both schemas +are unchanged, so current and frozen keys are unchanged. The lexical +`./a.php` is not an additional candidate. + +Controls added: + +* `component_equivalent_spellings_have_the_writer_key` gives the exact POSIX + and Windows reading for each case above. It compares the native writer with + the reading of the host that runs it. +* `the_host_reading_is_the_native_writer_on_every_short_path` compares the + native writer with the host reading for every path of up to six characters + over a name, `.` and the host separators, against every root of up to four: + 132,253 pairs on Linux. Windows paths that need a prefix are not generated. +* `a_component_equivalent_file_spelling_validates_with_the_writer_key` drives + this build's own `scan_files` report through `pons validate-report`, as + 0.5.0 and as 0.4.0, with its absolute root and with the relative label + `repo` in both separator styles. It rejects `./sample.php` as a record path, + as a fingerprint input, as both together, and in a frozen report. + +Local results on the fix: `cargo fmt --check` and all-target Clippy with +warnings denied passed. `cargo test --workspace --no-fail-fast` as root gave +266 passed and 3 failed. The three are the POSIX permission fixtures, which +refuse to run as root; they fail identically at `612145d` (263 passed, 3 +failed). The `pons-core` unit binary run as uid 1000 passed 146 of 146. +`tests/e2e.sh` on the release build gave 46 passed, 0 failed, 0 skipped, and +`tests/doc_drift.sh` passed. Three deliberate reader mutations (keep interior +`.`, drop the parent rule, keep trailing components) each failed both new +unit tests; the mutations are not committed. + +Limits. Drive, UNC and verbatim prefixes remain ordinary names in the reader, +as at `612145d`: a drive-letter case difference, a bare `C:` root and `.` +below a `\\?\` root are not modelled, and nothing here tests them. No Windows +host ran these tests locally; the hosted Linux and Windows checks belong to +the pull request. Creusot with Pearlite contracts and Verus remain `OPEN`, not +run. The tests, including the exhaustive comparison, are tests and not proofs. From 59f3464e654faf5adf28fd8ea46ebb9cc3697911 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 14:40:19 +0000 Subject: [PATCH 2/2] docs(echo-362): use a colon in the 10 November section heading Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_0136P7ZmAsYpFA9gxfQLF3F6 Signed-off-by: Claude --- docs/echo-362-verification.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/echo-362-verification.adoc b/docs/echo-362-verification.adoc index 5143d89..8407e4b 100644 --- a/docs/echo-362-verification.adoc +++ b/docs/echo-362-verification.adoc @@ -112,7 +112,7 @@ identity. Tests cover both 0.4.0 and 0.5.0 legacy forms and reject mixed interpretations; the Windows workspace suite passed 261 test executions, with all-target Clippy and the eight CLI contract tests passing. -== Component-equivalent paths — 10 November 2026 +== Component-equivalent paths: 10 November 2026 The review of #73 left one finding open. The writer and the reader disagreed on a file named through a component that `std::path` drops. For root `repo`