π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(watermark): SynthID-Text-style LLM text watermarking crate (Rust/WASM) (#3039)
rUvf7d27c362773
diff --git a/v3/crates/ruflo-watermark/.gitignore b/v3/crates/ruflo-watermark/.gitignorenew file mode 100644index 0000000000..f9cb237d05--- /dev/null+++ b/v3/crates/ruflo-watermark/.gitignore@@ -0,0 +1,12 @@+/target+# Session/agent tooling artifacts that land in the working dir β never source.+*.rvf+*.rvf.lock+*.rvf.idmap.json+*.db+*.db-shm+*.db-wal+.claude-flow/+.swarm/+.ruvnet-brain/+.ruvector/diff --git a/v3/crates/ruflo-watermark/Cargo.lock b/v3/crates/ruflo-watermark/Cargo.locknew file mode 100644index 0000000000..c7124d8987--- /dev/null+++ b/v3/crates/ruflo-watermark/Cargo.lock@@ -0,0 +1,478 @@+# This file is automatically @generated by Cargo.+# It is not intended for manual editing.+version = 3++[[package]]+name = "aho-corasick"+version = "1.1.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"+dependencies = [+ "memchr",+]++[[package]]+name = "anes"+version = "0.1.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4b46cbb362ab8752921c97e041f5e366ee6297bd428a31275b9fcf1e380f7299"++[[package]]+name = "anstyle"+version = "1.0.14"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"++[[package]]+name = "autocfg"+version = "1.5.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"++[[package]]+name = "bumpalo"+version = "3.20.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"++[[package]]+name = "cast"+version = "0.3.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5"++[[package]]+name = "cfg-if"+version = "1.0.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"++[[package]]+name = "ciborium"+version = "0.2.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "42e69ffd6f0917f5c029256a24d0161db17cea3997d185db0d35926308770f0e"+dependencies = [+ "ciborium-io",+ "ciborium-ll",+ "serde",+]++[[package]]+name = "ciborium-io"+version = "0.2.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "05afea1e0a06c9be33d539b876f1ce3692f4afea2cb41f740e7743225ed1c757"++[[package]]+name = "ciborium-ll"+version = "0.2.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "57663b653d948a338bfb3eeba9bb2fd5fcfaecb9e199e87e1eda4d9e8b240fd9"+dependencies = [+ "ciborium-io",+ "half",+]++[[package]]+name = "clap"+version = "4.6.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "473c7e07f409a8d772161724aa8db6a765a2532a70f9667eeb7b49d3d02fbdca"+dependencies = [+ "clap_builder",+]++[[package]]+name = "clap_builder"+version = "4.6.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "7b48fea5a88e9ae728a2dcbedbfc0e730f7d60da42e1cb049a83c9fb8b789889"+dependencies = [+ "anstyle",+ "clap_lex",+]++[[package]]+name = "clap_lex"+version = "1.1.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"++[[package]]+name = "criterion"+version = "0.5.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f2b12d017a929603d80db1831cd3a24082f8137ce19c69e6447f54f5fc8d692f"+dependencies = [+ "anes",+ "cast",+ "ciborium",+ "clap",+ "criterion-plot",+ "is-terminal",+ "itertools",+ "num-traits",+ "once_cell",+ "oorandom",+ "regex",+ "serde",+ "serde_derive",+ "serde_json",+ "tinytemplate",+ "walkdir",+]++[[package]]+name = "criterion-plot"+version = "0.5.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "6b50826342786a51a89e2da3a28f1c32b06e387201bc2d19791f622c673706b1"+dependencies = [+ "cast",+ "itertools",+]++[[package]]+name = "crunchy"+version = "0.2.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"++[[package]]+name = "either"+version = "1.17.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9e5e8f6c15a24b9a3ee5efec809ccd006d3b30e8b3bb63c39af737c7f87daa1d"++[[package]]+name = "half"+version = "2.7.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b"+dependencies = [+ "cfg-if",+ "crunchy",+ "zerocopy",+]++[[package]]+name = "hermit-abi"+version = "0.5.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "fc0fef456e4baa96da950455cd02c081ca953b141298e41db3fc7e36b1da849c"++[[package]]+name = "is-terminal"+version = "0.4.17"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"+dependencies = [+ "hermit-abi",+ "libc",+ "windows-sys",+]++[[package]]+name = "itertools"+version = "0.10.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "b0fd2260e829bddf4cb6ea802289de2f86d6a7a690192fbe91b3f46e0f2c8473"+dependencies = [+ "either",+]++[[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.189"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"++[[package]]+name = "memchr"+version = "2.8.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"++[[package]]+name = "num-traits"+version = "0.2.19"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"+dependencies = [+ "autocfg",+]++[[package]]+name = "once_cell"+version = "1.21.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"++[[package]]+name = "oorandom"+version = "11.1.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e"++[[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 = "regex"+version = "1.13.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"+dependencies = [+ "aho-corasick",+ "memchr",+ "regex-automata",+ "regex-syntax",+]++[[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 = "ruflo-watermark"+version = "0.1.0"+dependencies = [+ "criterion",+ "wasm-bindgen",+]++[[package]]+name = "rustversion"+version = "1.0.23"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"++[[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 = "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 3.0.3",+]++[[package]]+name = "serde_json"+version = "1.0.151"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"+dependencies = [+ "itoa",+ "memchr",+ "serde",+ "serde_core",+ "zmij",+]++[[package]]+name = "syn"+version = "2.0.119"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"+dependencies = [+ "proc-macro2",+ "quote",+ "unicode-ident",+]++[[package]]+name = "syn"+version = "3.0.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"+dependencies = [+ "proc-macro2",+ "quote",+ "unicode-ident",+]++[[package]]+name = "tinytemplate"+version = "1.2.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "be4d6b5f19ff7664e8c98d03e2139cb510db9b0a60b55f8e8709b689d939b6bc"+dependencies = [+ "serde",+ "serde_json",+]++[[package]]+name = "unicode-ident"+version = "1.0.24"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"++[[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 = "wasm-bindgen"+version = "0.2.127"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1b70935747edd64d89de3efa29d73789b806c15798f8e7dca4d8ac356b50ce70"+dependencies = [+ "cfg-if",+ "once_cell",+ "rustversion",+ "wasm-bindgen-macro",+ "wasm-bindgen-shared",+]++[[package]]+name = "wasm-bindgen-macro"+version = "0.2.127"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "77775f8f3f7217702089053b94958f8f54061a3f663417df76e19cbdcca29bc1"+dependencies = [+ "quote",+ "wasm-bindgen-macro-support",+]++[[package]]+name = "wasm-bindgen-macro-support"+version = "0.2.127"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e11d33f857dc2fb11b8bc75aee111aa9cbeb12cd9f25efd3d4c2a3dd4e235284"+dependencies = [+ "bumpalo",+ "proc-macro2",+ "quote",+ "syn 2.0.119",+ "wasm-bindgen-shared",+]++[[package]]+name = "wasm-bindgen-shared"+version = "0.2.127"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "7ef64dbcc55df09c7e5a46182d181c2cfa3e925f3da937ea764728b4bbb9dcbf"+dependencies = [+ "unicode-ident",+]++[[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 = "zerocopy"+version = "0.8.56"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "556764e583adb45a9f8d413c2a147fa7e8d821e48e12b14fd560b607998b75eb"+dependencies = [+ "zerocopy-derive",+]++[[package]]+name = "zerocopy-derive"+version = "0.8.56"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f2ab42fc20575779bd240faa45f94a74256f755c0fa9e89f0ede20d91d0cdfc1"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 2.0.119",+]++[[package]]+name = "zmij"+version = "1.0.23"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"diff --git a/v3/crates/ruflo-watermark/Cargo.toml b/v3/crates/ruflo-watermark/Cargo.tomlnew file mode 100644index 0000000000..d7e6850771--- /dev/null+++ b/v3/crates/ruflo-watermark/Cargo.toml@@ -0,0 +1,44 @@+# ruflo-watermark β SynthID-Text-style LLM text watermarking (generation ++# detection) plus a robustness-evaluation harness.+#+# Self-contained `[workspace]` so this crate builds standalone (`cargo test`,+# `cargo build --target wasm32-unknown-unknown`) WITHOUT being pulled into+# ruflo's parent workspace resolution β the parent root Cargo.toml documents+# why nested workspace roots must stay isolated. It is equally droppable into+# agent-harness-generator/crates/ as a plain member.+[package]+name = "ruflo-watermark"+version = "0.1.0"+edition = "2021"+rust-version = "1.74"+license = "MIT"+description = "High-speed SynthID-Text-style LLM text watermarking (Tournament + distortion-free Gumbel) with Bayesian detection and a robustness-evaluation harness. Rust core + optional WASM bindings."+repository = "https://github.com/ruvnet/ruflo"+keywords = ["watermark", "llm", "synthid", "provenance", "wasm"]+categories = ["algorithms", "text-processing", "wasm"]++[workspace]++[lib]+crate-type = ["cdylib", "rlib"]++[features]+default = ["std"]+std = []+# WASM bindings. Build: `cargo build --release --features wasm --target wasm32-unknown-unknown`+wasm = ["dep:wasm-bindgen"]++[dependencies]+wasm-bindgen = { version = "0.2", optional = true }++[dev-dependencies]+criterion = { version = "0.5", default-features = false, features = ["cargo_bench_support"] }++[[bench]]+name = "throughput"+harness = false++[profile.release]+opt-level = 3+lto = "fat"+codegen-units = 1diff --git a/v3/crates/ruflo-watermark/benches/throughput.rs b/v3/crates/ruflo-watermark/benches/throughput.rsnew file mode 100644index 0000000000..a71052f3fd--- /dev/null+++ b/v3/crates/ruflo-watermark/benches/throughput.rs@@ -0,0 +1,53 @@+//! Throughput benchmarks: per-token generation cost for both schemes and the+//! detector scan rate. These quantify the "negligible impact on speed" claim β+//! watermarking is a handful of hashes per emitted token.++use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};+use ruflo_watermark::{detect_gumbel, detect_tournament, Scheme, WatermarkConfig, WatermarkKey, Watermarker};++fn candidates(vocab: u32) -> (Vec<u32>, Vec<f32>) {+ let tokens: Vec<u32> = (0..vocab).collect();+ let probs = vec![1.0f32 / vocab as f32; vocab as usize];+ (tokens, probs)+}++fn bench_generation(c: &mut Criterion) {+ let (tokens, probs) = candidates(256);+ let mut group = c.benchmark_group("generation_per_token");+ group.throughput(Throughput::Elements(1));++ for depth in [2u32, 4, 8] {+ let cfg = WatermarkConfig::new(WatermarkKey(1)).with_layers(depth);+ group.bench_with_input(BenchmarkId::new("tournament_depth", depth), &depth, |b, _| {+ let mut wm = Watermarker::new(cfg, Scheme::Tournament);+ b.iter(|| wm.step(&tokens, &probs));+ });+ }++ let cfg = WatermarkConfig::new(WatermarkKey(1)).with_layers(1);+ group.bench_function("gumbel", |b| {+ let mut wm = Watermarker::new(cfg, Scheme::Gumbel);+ b.iter(|| wm.step(&tokens, &probs));+ });+ group.finish();+}++fn bench_detection(c: &mut Criterion) {+ let (tokens, probs) = candidates(256);+ let cfg = WatermarkConfig::new(WatermarkKey(1)).with_layers(6);+ let mut wm = Watermarker::new(cfg, Scheme::Tournament);+ let stream: Vec<u32> = (0..2000).map(|_| tokens[wm.step(&tokens, &probs)]).collect();++ let mut group = c.benchmark_group("detection");+ group.throughput(Throughput::Elements(stream.len() as u64));+ group.bench_function("tournament_scan", |b| b.iter(|| detect_tournament(&stream, cfg)));++ let cfg_g = WatermarkConfig::new(WatermarkKey(1)).with_layers(1);+ let mut wmg = Watermarker::new(cfg_g, Scheme::Gumbel);+ let stream_g: Vec<u32> = (0..2000).map(|_| tokens[wmg.step(&tokens, &probs)]).collect();+ group.bench_function("gumbel_scan", |b| b.iter(|| detect_gumbel(&stream_g, cfg_g)));+ group.finish();+}++criterion_group!(benches, bench_generation, bench_detection);+criterion_main!(benches);diff --git a/v3/crates/ruflo-watermark/src/align.rs b/v3/crates/ruflo-watermark/src/align.rsnew file mode 100644index 0000000000..9a04c5f7ab--- /dev/null+++ b/v3/crates/ruflo-watermark/src/align.rs@@ -0,0 +1,235 @@+//! Indel-robust detection via context self-synchronization + local alignment.+//!+//! ## The gap this closes+//!+//! The position-locked detector ([`crate::detect`]) is substitution-robust but+//! degrades under deletion/insertion. The dominant failure mode is NOT the+//! per-token seed β that *self-synchronizes*: once an edit has slid out of the+//! `H`-token context window, the observed window is again a run of consecutive+//! generated tokens, so `context_seed` matches what the generator used and the+//! token scores correctly. The real losses are (1) the `H` "straddle" positions+//! after each edit whose window contains the edit, and (2) **repeated-context+//! masking desync**: an indel makes the detector's `seen` set diverge from the+//! generator's, so masking decisions differ and scored positions no longer line+//! up, injecting noise across the whole tail.+//!+//! ## The fix, in two layers+//!+//! 1. **Self-sync scoring** ([`detect_gumbel_selfsync`]): score *every* position+//! from its observed local window with **masking off**. This removes failure+//! mode (2) entirely and keeps closed-form calibration (each position is one+//! `Exp(1)` term under the null), while the self-syncing context recovers all+//! non-straddle positions after an edit. Big, cheap win.+//!+//! 2. **Local alignment** ([`detect_gumbel_aligned`]): a gap-tolerant maximum-+//! segment scan over the centered score-terms concentrates the statistic on+//! genuinely watermarked spans and *bridges over* straddle/inserted runs+//! (paying a tunable gap penalty), instead of diluting the sum with their+//! null noise. Calibrated against an empirical null (the same alignment run+//! under a wrong key), so the max-over-paths inflation is accounted for. Its+//! parameters are what the Darwin/flywheel tuner in [`crate::evolve`] fits.++use crate::context::WatermarkConfig;+use crate::detect::{DetectionResult, Scheme};+use crate::gumbel::score_term;+use crate::hash::{context_seed, WatermarkKey};++/// Per-position centered Gumbel score `score_term - 1` computed from the+/// observed local window with masking OFF. Mean ~0 under the null, positive on+/// intact watermarked spans. Positions before a full window exist are scored on+/// the short prefix (weaker, but self-consistent with the generator's own+/// short-prefix seeding).+fn centered_scores(tokens: &[u32], key: WatermarkKey, h: usize) -> Vec<f64> {+ let mut out = Vec::with_capacity(tokens.len());+ for t in 0..tokens.len() {+ let start = t.saturating_sub(h);+ let seed = context_seed(key, &tokens[start..t]);+ out.push(score_term(seed, tokens[t]) - 1.0);+ }+ out+}++/// Self-synchronizing indel-robust detector (layer 1). Closed-form: the sum of+/// centered score-terms is `Normal(0, n)` under the null, so `z = Ξ£c / sqrt(n)`.+/// No masking, no calibration, no parameters β the cheap robustness win.+pub fn detect_gumbel_selfsync(tokens: &[u32], cfg: WatermarkConfig) -> DetectionResult {+ let c = centered_scores(tokens, cfg.key, cfg.context_width);+ let n = c.len() as f64;+ let sum: f64 = c.iter().sum();+ let std = n.sqrt();+ let z = if std > 0.0 { sum / std } else { 0.0 };+ let (p, lp) = crate::detect::normal_upper_tail(z);+ DetectionResult {+ scheme: Scheme::Gumbel,+ scored_positions: c.len(),+ statistic: sum,+ null_mean: 0.0,+ z_score: z,+ p_value: p,+ log10_p: lp,+ }+}++/// Tunable parameters for the local-alignment detector (layer 2). These are the+/// search space for [`crate::evolve`].+#[derive(Clone, Copy, Debug, PartialEq)]+pub struct AlignParams {+ /// Max consecutive low/straddle positions a segment may bridge over.+ pub band: usize,+ /// Score paid per bridged position (the gap penalty). Higher => stingier+ /// bridging, less null inflation, but less indel recovery.+ pub gap_penalty: f64,+ /// Number of wrong-key null replays used to calibrate the max statistic.+ pub null_replays: u32,+}++impl Default for AlignParams {+ fn default() -> Self {+ AlignParams {+ band: 6,+ gap_penalty: 0.5,+ null_replays: 24,+ }+ }+}++/// Gap-tolerant maximum-segment score. `dp[t]` = best segment ending at `t`; a+/// segment may extend from up to `band` positions back, paying `gap_penalty`+/// per skipped position. Returns the global maximum (Smith-Waterman-like, `O(nΒ·band)`).+fn local_align_max(scores: &[f64], p: &AlignParams) -> f64 {+ if scores.is_empty() {+ return 0.0;+ }+ let mut dp = vec![0.0f64; scores.len()];+ let mut best = f64::MIN;+ for t in 0..scores.len() {+ // Start fresh at t, or extend the best reachable predecessor within band.+ let mut prev_best = 0.0f64; // "start new segment here"+ let lo = t.saturating_sub(p.band);+ for k in lo..t {+ let gap = (t - k - 1) as f64 * p.gap_penalty; // positions skipped between k and t+ let cand = dp[k] - gap;+ if cand > prev_best {+ prev_best = cand;+ }+ }+ dp[t] = prev_best + scores[t];+ if dp[t] > best {+ best = dp[t];+ }+ }+ best+}++/// Local-alignment indel-robust detector (layer 2), empirically calibrated.+///+/// Computes the gap-tolerant max-segment score on the real key, then on+/// `null_replays` wrong keys (same tokens, so identical marginal statistics),+/// and standardizes: `z = (obs - mean_null) / sd_null`. This accounts for the+/// max-over-paths inflation that would otherwise make a naive p-value anti-+/// conservative.+pub fn detect_gumbel_aligned(+ tokens: &[u32],+ cfg: WatermarkConfig,+ params: AlignParams,+) -> DetectionResult {+ let real = centered_scores(tokens, cfg.key, cfg.context_width);+ let obs = local_align_max(&real, ¶ms);++ // Empirical null: replay under deterministically-perturbed wrong keys.+ let k = params.null_replays.max(2);+ let mut vals = Vec::with_capacity(k as usize);+ for r in 0..k {+ let wrong = WatermarkKey(crate::hash::mix64(cfg.key.0 ^ (0xA5A5_0000 ^ r as u64)));+ let s = centered_scores(tokens, wrong, cfg.context_width);+ vals.push(local_align_max(&s, ¶ms));+ }+ let mean = vals.iter().sum::<f64>() / vals.len() as f64;+ let var = vals.iter().map(|v| (v - mean) * (v - mean)).sum::<f64>() / (vals.len() as f64 - 1.0).max(1.0);+ let sd = var.sqrt().max(1e-9);+ let z = (obs - mean) / sd;+ let (p, lp) = crate::detect::normal_upper_tail(z);+ DetectionResult {+ scheme: Scheme::Gumbel,+ scored_positions: tokens.len(),+ statistic: obs,+ null_mean: mean,+ z_score: z,+ p_value: p,+ log10_p: lp,+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::hash::WatermarkKey;+ use crate::robustness::attack_delete;+ use crate::{Scheme, Watermarker};++ fn watermarked(n: usize, vocab: u32, cfg: WatermarkConfig) -> Vec<u32> {+ let tokens: Vec<u32> = (0..vocab).collect();+ let probs = vec![1.0f32 / vocab as f32; vocab as usize];+ let mut wm = Watermarker::new(cfg, Scheme::Gumbel);+ (0..n).map(|_| tokens[wm.step(&tokens, &probs)]).collect()+ }++ // Build a stream in one of two regimes: flat large-vocab (masking rarely+ // fires) or skewed small-vocab (repeated contexts => masking fires often,+ // like real text with recurring phrases).+ fn regime_stream(vocab: u32, rep_bias: bool, n: usize, cfg: WatermarkConfig) -> Vec<u32> {+ let tokens: Vec<u32> = (0..vocab).collect();+ let probs: Vec<f32> = if rep_bias {+ let mut p = vec![0.02f32; vocab as usize];+ p[0] = 1.0 - 0.02 * (vocab as f32 - 1.0);+ p+ } else {+ vec![1.0f32 / vocab as f32; vocab as usize]+ };+ let mut wm = Watermarker::new(cfg, Scheme::Gumbel);+ (0..n).map(|_| tokens[wm.step(&tokens, &probs)]).collect()+ }++ #[test]+ fn selfsync_fixes_masking_desync_the_real_indel_gap() {+ // The headline, honest result: in the repeated-context regime the+ // position-locked detector is near-dead (masking desync), while self-sync+ // stays strong AND indel-robust across deletion rates.+ let cfg = WatermarkConfig::new(WatermarkKey::from_bytes(b"indel")).with_layers(1);+ let stream = regime_stream(12, true, 1800, cfg);+ for rate in [0.0f64, 0.35, 0.5] {+ let attacked = attack_delete(&stream, rate, 0xD00D);+ let locked = crate::detect::detect_gumbel(&attacked, cfg).z_score;+ let ss = detect_gumbel_selfsync(&attacked, cfg).z_score;+ assert!(ss > locked + 10.0, "self-sync ({ss}) did not dominate locked ({locked}) at del={rate}");+ assert!(ss > 8.0, "self-sync collapsed at del={rate}: z={ss}");+ }+ }++ #[test]+ fn selfsync_never_worse_than_position_locked() {+ // In the flat regime masking rarely fires, so the two must agree closely+ // (self-sync is never a regression on the position-locked detector).+ let cfg = WatermarkConfig::new(WatermarkKey::from_bytes(b"flat")).with_layers(1);+ let stream = regime_stream(256, false, 1500, cfg);+ let attacked = attack_delete(&stream, 0.2, 0xBEEF);+ let locked = crate::detect::detect_gumbel(&attacked, cfg).z_score;+ let ss = detect_gumbel_selfsync(&attacked, cfg).z_score;+ assert!(ss >= locked - 0.5, "self-sync regressed vs locked: {ss} < {locked}");+ }++ #[test]+ fn aligned_detects_under_heavy_deletion_and_calibrates_null() {+ let cfg = WatermarkConfig::new(WatermarkKey(0x1357)).with_layers(1);+ let stream = watermarked(2000, 256, cfg);+ let attacked = attack_delete(&stream, 0.25, 0x1234);++ let r = detect_gumbel_aligned(&attacked, cfg, AlignParams::default());+ assert!(r.z_score > 4.0, "aligned detector too weak under 25% deletion: z={}", r.z_score);++ // Null: a stream that never used the key must not calibrate as watermarked.+ let null: Vec<u32> = (0..2000u32).map(|i| (crate::hash::mix64(i as u64) % 256) as u32).collect();+ let rn = detect_gumbel_aligned(&null, cfg, AlignParams::default());+ assert!(!rn.is_watermarked(1e-3), "aligned detector false-positive on null: z={}", rn.z_score);+ }+}diff --git a/v3/crates/ruflo-watermark/src/bayes.rs b/v3/crates/ruflo-watermark/src/bayes.rsnew file mode 100644index 0000000000..54d0732e5d--- /dev/null+++ b/v3/crates/ruflo-watermark/src/bayes.rs@@ -0,0 +1,255 @@+//! Higher-power detectors for short texts.+//!+//! The mean/sum detectors in [`crate::detect`] use a normal approximation to the+//! null. That is fine for long texts but (a) is inaccurate in the tail for small+//! `n` β exactly the short-text regime Anthropic flags as hard β and (b) is not+//! the most powerful test when the watermark signal is *sparse* (a few strong+//! positions among many null ones, as in low-entropy / mostly-factual text).+//!+//! Two upgrades, both for the distortion-free Gumbel scheme (whose per-token+//! statistic has a clean closed form):+//!+//! 1. [`detect_gumbel_exact`] β replaces the normal tail with the **exact**+//! `Gamma(n, 1)` upper tail (the true null of a sum of `n` `Exp(1)` terms).+//! Correct, not anti-conservative, at any `n`.+//! 2. [`detect_gumbel_hc`] β a **Higher Criticism** statistic (DonohoβJin) over+//! the per-token null tail probabilities. Provably more powerful than the sum+//! when the signal is sparse, which is the short/low-entropy case.++use crate::context::{ContextTracker, WatermarkConfig};+use crate::detect::{DetectionResult, Scheme};+use crate::gumbel::score_term;++/// Per-watermarked-position Gumbel score terms (masking-aware, matching the+/// generator), for the exact/HC detectors to consume.+fn score_terms(tokens: &[u32], cfg: WatermarkConfig) -> Vec<f64> {+ let mut tracker = ContextTracker::new(cfg);+ let mut out = Vec::new();+ for &tok in tokens {+ let ps = tracker.peek();+ if ps.watermarked {+ out.push(score_term(ps.seed, tok));+ }+ tracker.advance(ps, tok);+ }+ out+}++/// Ln Ξ(x) via the Lanczos approximation (g=7, n=9). Accurate to ~1e-13 for+/// x > 0 β enough for exact incomplete-gamma p-values.+fn ln_gamma(x: f64) -> f64 {+ const G: f64 = 7.0;+ const C: [f64; 9] = [+ 0.999_999_999_999_809_93,+ 676.520_368_121_885_1,+ -1_259.139_216_722_402_8,+ 771.323_428_777_653_1,+ -176.615_029_162_140_6,+ 12.507_343_278_686_905,+ -0.138_571_095_265_720_12,+ 9.984_369_578_019_572e-6,+ 1.505_632_735_149_311_6e-7,+ ];+ if x < 0.5 {+ // Reflection: Ξ(x)Ξ(1-x) = Ο / sin(Οx).+ (core::f64::consts::PI / (core::f64::consts::PI * x).sin()).ln() - ln_gamma(1.0 - x)+ } else {+ let x = x - 1.0;+ let mut a = C[0];+ let t = x + G + 0.5;+ for (i, &c) in C.iter().enumerate().skip(1) {+ a += c / (x + i as f64);+ }+ 0.5 * (2.0 * core::f64::consts::PI).ln() + (x + 0.5) * t.ln() - t + a.ln()+ }+}++/// Regularized upper incomplete gamma `Q(a, x) = P(Gamma(a,1) > x)`.+/// Series expansion for `x < a+1`, continued fraction otherwise (Numerical+/// Recipes `gammq`). Returns a probability in `[0, 1]`.+fn gammq(a: f64, x: f64) -> f64 {+ if x <= 0.0 {+ return 1.0;+ }+ if x < a + 1.0 {+ // Lower series P(a,x), then Q = 1 - P.+ let mut ap = a;+ let mut sum = 1.0 / a;+ let mut del = sum;+ for _ in 0..1000 {+ ap += 1.0;+ del *= x / ap;+ sum += del;+ if del.abs() < sum.abs() * 1e-15 {+ break;+ }+ }+ let p = sum * (-x + a * x.ln() - ln_gamma(a)).exp();+ (1.0 - p).clamp(0.0, 1.0)+ } else {+ // Lentz continued fraction for Q directly.+ let tiny = 1e-300;+ let mut b = x + 1.0 - a;+ let mut c = 1.0 / tiny;+ let mut d = 1.0 / b;+ let mut h = d;+ for i in 1..1000 {+ let an = -(i as f64) * (i as f64 - a);+ b += 2.0;+ d = an * d + b;+ if d.abs() < tiny {+ d = tiny;+ }+ c = b + an / c;+ if c.abs() < tiny {+ c = tiny;+ }+ d = 1.0 / d;+ let del = d * c;+ h *= del;+ if (del - 1.0).abs() < 1e-15 {+ break;+ }+ }+ (h * (-x + a * x.ln() - ln_gamma(a)).exp()).clamp(0.0, 1.0)+ }+}++/// Exact-null Gumbel detector: the statistic is `S = Ξ£ score_term` (sum of `n`+/// `Exp(1)` terms under the null), and the p-value is the **exact**+/// `P(Gamma(n,1) > S)`. Same statistic as [`crate::detect::detect_gumbel`], but+/// a correct tail at small `n` where the normal approximation misleads.+pub fn detect_gumbel_exact(tokens: &[u32], cfg: WatermarkConfig) -> DetectionResult {+ let s = score_terms(tokens, cfg);+ let n = s.len();+ let sum: f64 = s.iter().sum();+ let p = if n == 0 { 0.5 } else { gammq(n as f64, sum) };+ let lp = if p > 0.0 { p.log10() } else { f64::NEG_INFINITY };+ // Report a normal-equiv z for a comparable field, but the p-value is exact.+ let z = if n > 0 { (sum - n as f64) / (n as f64).sqrt() } else { 0.0 };+ DetectionResult {+ scheme: Scheme::Gumbel,+ scored_positions: n,+ statistic: sum,+ null_mean: n as f64,+ z_score: z,+ p_value: p,+ log10_p: lp,+ }+}++/// Standard-normal upper-tail probability, reused for per-token p-values.+fn norm_q(z: f64) -> f64 {+ crate::detect::normal_upper_tail(z).0.max(1e-300)+}++/// Higher-Criticism detector (DonohoβJin). Converts each token's score term to a+/// null tail p-value `p_i = P(Exp(1) > s_i) = e^{-s_i}`, sorts them, and forms+/// `HC = max_i sqrt(n) (i/n - p_(i)) / sqrt(p_(i)(1-p_(i)))` over the smaller+/// half. Large HC β more small p-values than chance β watermark. Provably more+/// powerful than the sum when only a sparse subset of tokens carries signal+/// (the low-entropy / short-text case). Calibrated to a standard-normal tail via+/// the HC null approximation.+pub fn detect_gumbel_hc(tokens: &[u32], cfg: WatermarkConfig) -> DetectionResult {+ let s = score_terms(tokens, cfg);+ let n = s.len();+ if n == 0 {+ return DetectionResult {+ scheme: Scheme::Gumbel,+ scored_positions: 0,+ statistic: 0.0,+ null_mean: 0.0,+ z_score: 0.0,+ p_value: 0.5,+ log10_p: 0.5f64.log10(),+ };+ }+ // Per-token null tail p-values (score_term ~ Exp(1) under H0).+ let mut ps: Vec<f64> = s.iter().map(|&x| (-x).exp().clamp(1e-300, 1.0)).collect();+ ps.sort_by(|a, b| a.partial_cmp(b).unwrap());+ let nf = n as f64;+ let mut hc = f64::MIN;+ // Search the smaller-p half (standard HC+ truncation avoids the noisy tail).+ for i in 1..=(n / 2).max(1) {+ let pi = ps[i - 1];+ let denom = (pi * (1.0 - pi)).sqrt().max(1e-12);+ let stat = nf.sqrt() * (i as f64 / nf - pi) / denom;+ if stat > hc {+ hc = stat;+ }+ }+ // HC's null grows like sqrt(2 log log n); standardize to a normal-ish z so+ // the p-value is comparable and conservative.+ let norm = (2.0 * (nf.ln()).max(1.0).ln().max(1.0)).sqrt();+ let z = hc - norm; // centered HC statistic+ let p = norm_q(z.max(0.0));+ let lp = if p > 0.0 { p.log10() } else { f64::NEG_INFINITY };+ DetectionResult {+ scheme: Scheme::Gumbel,+ scored_positions: n,+ statistic: hc,+ null_mean: norm,+ z_score: z,+ p_value: p,+ log10_p: lp,+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::hash::{mix64, WatermarkKey};+ use crate::{Scheme, Watermarker};++ fn watermarked(n: usize, vocab: u32, cfg: WatermarkConfig) -> Vec<u32> {+ let tokens: Vec<u32> = (0..vocab).collect();+ let probs = vec![1.0f32 / vocab as f32; vocab as usize];+ let mut wm = Watermarker::new(cfg, Scheme::Gumbel);+ (0..n).map(|_| tokens[wm.step(&tokens, &probs)]).collect()+ }++ #[test]+ fn ln_gamma_and_gammq_are_accurate() {+ // Ξ(5)=24 => ln 24; Q(1,x)=e^{-x} (Exp(1) tail).+ assert!((ln_gamma(5.0) - 24.0f64.ln()).abs() < 1e-9);+ // Gamma(1,1) = Exp(1): Q(1,x) = e^{-x}.+ assert!((gammq(1.0, 2.0) - (-2.0f64).exp()).abs() < 1e-9);+ // Gamma(2,1): Q(2,x) = e^{-x}(1+x), exact. Q(2,1) = 2/e.+ assert!((gammq(2.0, 1.0) - 2.0 / core::f64::consts::E).abs() < 1e-9);+ // Continued-fraction branch (x >= a+1): Q(2,5) = e^{-5}Β·6.+ assert!((gammq(2.0, 5.0) - (-5.0f64).exp() * 6.0).abs() < 1e-9);+ }++ #[test]+ fn exact_pvalue_is_calibrated_on_null() {+ // A null stream must not be flagged by the exact detector.+ let cfg = WatermarkConfig::new(WatermarkKey(0x9)).with_layers(1);+ let null: Vec<u32> = (0..300u32).map(|i| (mix64(i as u64 ^ 0xAA) % 256) as u32).collect();+ let r = detect_gumbel_exact(&null, cfg);+ assert!(r.p_value > 1e-3, "exact detector false-positive on null: p={}", r.p_value);+ }++ #[test]+ fn exact_detects_short_watermark() {+ // The short-text win: the exact Gamma tail flags a short watermarked+ // text with a correct (not anti-conservative) p-value.+ let cfg = WatermarkConfig::new(WatermarkKey::from_bytes(b"short")).with_layers(1);+ let stream = watermarked(120, 256, cfg);+ let exact = detect_gumbel_exact(&stream, cfg);+ assert!(exact.p_value < 1e-3, "exact detector missed short watermark: p={}", exact.p_value);+ }++ #[test]+ fn hc_is_calibrated_and_detects() {+ // Higher Criticism must (a) not false-positive on null and (b) fire on a+ // clearly watermarked text. Its edge over the sum is in the sparse+ // regime; here we assert calibration + detection, the defensible claims.+ let cfg = WatermarkConfig::new(WatermarkKey::from_bytes(b"hc")).with_layers(1);+ let stream = watermarked(400, 256, cfg);+ let hc = detect_gumbel_hc(&stream, cfg);+ let null: Vec<u32> = (0..400u32).map(|i| (mix64(i as u64 ^ 0x1234) % 256) as u32).collect();+ let hc_null = detect_gumbel_hc(&null, cfg);+ assert!(hc_null.p_value > 1e-2, "HC false-positive on null: p={}", hc_null.p_value);+ assert!(hc.z_score > hc_null.z_score + 1.0, "HC did not separate watermark from null: {} vs {}", hc.z_score, hc_null.z_score);+ }+}diff --git a/v3/crates/ruflo-watermark/src/context.rs b/v3/crates/ruflo-watermark/src/context.rsnew file mode 100644index 0000000000..22ba7891e0--- /dev/null+++ b/v3/crates/ruflo-watermark/src/context.rs@@ -0,0 +1,162 @@+//! Context window management and repeated-context masking.+//!+//! The watermark's randomness at position `t` is seeded by the preceding `H`+//! tokens (the *watermarking context window*, `h` in the SynthID paper). Two+//! subtleties this module handles:+//!+//! 1. **Sliding window.** Positions before `H` tokens exist have a short/empty+//! context; we seed on whatever prefix is available so early tokens still+//! carry (weaker) signal.+//!+//! 2. **Repeated-context masking.** If the same `H`-gram context recurs, re-using+//! the same random stream would (a) bias the distribution on repetitive text+//! and (b) hand an attacker a trivial correlation. SynthID-Text skips+//! watermarking (samples from the *unmodified* model distribution) whenever a+//! context h-gram has already been seen. This is what makes the scheme+//! distribution-preserving in expectation and robust to "repeat the prompt"+//! attacks. The detector applies the identical mask so scored positions match+//! generated ones exactly.++use crate::hash::{context_seed, WatermarkKey};++/// Configuration shared by generator and detector. Both MUST use identical+/// settings or the recomputed g-value stream will not line up.+#[derive(Clone, Copy, Debug)]+pub struct WatermarkConfig {+ /// Secret key. Carries no user information.+ pub key: WatermarkKey,+ /// Context window size `H` (number of preceding tokens seeding each draw).+ /// Larger `H` => more distortion-free and repetition-robust, but early+ /// tokens carry less signal and short texts are harder to detect.+ pub context_width: usize,+ /// Number of tournament layers `m` (SynthID). More layers => stronger+ /// watermark per token (more bias) at more compute. Ignored by the+ /// distortion-free Gumbel scheme.+ pub layers: u32,+ /// Enable repeated-context masking (recommended: `true`).+ pub repeated_context_mask: bool,+}++impl WatermarkConfig {+ /// Sensible defaults matching the SynthID-Text paper's practical regime:+ /// `H = 4`, `m = 30` tournament layers, masking on.+ pub fn new(key: WatermarkKey) -> Self {+ WatermarkConfig {+ key,+ context_width: 4,+ layers: 30,+ repeated_context_mask: true,+ }+ }++ pub fn with_context_width(mut self, h: usize) -> Self {+ self.context_width = h.max(1);+ self+ }++ pub fn with_layers(mut self, m: u32) -> Self {+ self.layers = m.max(1);+ self+ }+}++/// Streaming context tracker. Feed it the tokens as they are generated (or, at+/// detection time, as they are read) and it yields, per position, the random+/// seed to use and whether this position is *watermarked* (unmasked) or should+/// be skipped (masked because its context repeated).+pub struct ContextTracker {+ cfg: WatermarkConfig,+ history: Vec<u32>,+ /// Seeds of context h-grams already emitted, for repeated-context masking.+ /// A seed collision is astronomically unlikely with a 64-bit mixer, so we+ /// store seeds (8 bytes) rather than the raw h-grams.+ seen: Vec<u64>,+}++/// The watermarking decision for a single position.+#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub struct PositionSeed {+ /// The random seed `r` for this position.+ pub seed: u64,+ /// Whether this position is watermarked. If `false` (masked), the generator+ /// samples from the unmodified model distribution and the detector ignores+ /// the position β the two stay in lockstep.+ pub watermarked: bool,+}++impl ContextTracker {+ pub fn new(cfg: WatermarkConfig) -> Self {+ ContextTracker {+ cfg,+ history: Vec::new(),+ seen: Vec::new(),+ }+ }++ /// Compute the seed for the *next* position from current history, and decide+ /// masking. Does NOT advance β call [`ContextTracker::advance`] once the+ /// token at this position is known.+ pub fn peek(&self) -> PositionSeed {+ let start = self.history.len().saturating_sub(self.cfg.context_width);+ let ctx = &self.history[start..];+ let seed = context_seed(self.cfg.key, ctx);+ let watermarked = if self.cfg.repeated_context_mask {+ !self.seen.contains(&seed)+ } else {+ true+ };+ PositionSeed { seed, watermarked }+ }++ /// Record the emitted `token` and, if this position was watermarked, mark its+ /// context seed as seen so a future recurrence is masked.+ pub fn advance(&mut self, seed: PositionSeed, token: u32) {+ if self.cfg.repeated_context_mask && seed.watermarked {+ self.seen.push(seed.seed);+ }+ self.history.push(token);+ }++ pub fn config(&self) -> &WatermarkConfig {+ &self.cfg+ }+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn repeated_context_is_masked() {+ let cfg = WatermarkConfig::new(WatermarkKey(1)).with_context_width(2);+ let mut t = ContextTracker::new(cfg);+ // Emit tokens A B A B A B β the context "A B" recurs.+ let seq = [10u32, 20, 10, 20, 10, 20];+ let mut watermarked_flags = Vec::new();+ for &tok in &seq {+ let ps = t.peek();+ watermarked_flags.push(ps.watermarked);+ t.advance(ps, tok);+ }+ // First occurrence of each distinct context is watermarked; recurrences+ // of "10,20" -> masked. Position 4 has context [20,10] (from idx2,3),+ // position 5 has context [10,20] again (seen) => masked.+ assert!(watermarked_flags[5] == false, "recurring context not masked");+ }++ #[test]+ fn masking_off_never_masks() {+ let cfg = WatermarkConfig {+ key: WatermarkKey(1),+ context_width: 1,+ layers: 1,+ repeated_context_mask: false,+ };+ let mut t = ContextTracker::new(cfg);+ for &tok in &[1u32, 1, 1, 1] {+ let ps = t.peek();+ assert!(ps.watermarked);+ t.advance(ps, tok);+ }+ }+}diff --git a/v3/crates/ruflo-watermark/src/detect.rs b/v3/crates/ruflo-watermark/src/detect.rsnew file mode 100644index 0000000000..53fa1b2535--- /dev/null+++ b/v3/crates/ruflo-watermark/src/detect.rs@@ -0,0 +1,228 @@+//! Detection: given an emitted token sequence and the key, recover the evidence+//! that it rode the watermark's pseudo-random stream, and turn it into a+//! calibrated statistic + p-value.+//!+//! The detector re-runs the exact [`ContextTracker`] the generator used (same+//! key, context width, and repeated-context mask), so the set of *scored*+//! positions is identical to the set of *watermarked* positions. For each scored+//! position it computes the scheme's per-token contribution:+//!+//! - **Tournament**: the `d` layer g-bits of the emitted token. Under the null+//! (no watermark) each bit is a fair coin, so the total is `Binomial(N, Β½)`+//! with `N = positions Γ d`. A watermarked winner won every round, so its bits+//! skew to 1 (`E β 2/3` per layer). Statistic: standardized excess of ones.+//! - **Gumbel**: `-ln(1 - u)` for the emitted token. Under the null each term is+//! `Exp(1)` (mean 1), so the sum is `Gamma(n, 1)`; the watermark inflates the+//! mean. Statistic: standardized excess over `n`.+//!+//! Both reduce to an upper-tail standard-normal p-value. A small p-value means+//! "this text is very unlikely to have been produced without the key" β i.e.+//! likely watermarked.++use crate::context::{ContextTracker, WatermarkConfig};+use crate::gumbel::score_term;+use crate::hash::g_bit;++/// Which scheme produced (or is hypothesized to have produced) the watermark.+#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub enum Scheme {+ /// SynthID-Text tournament (fair-coin g) with depth = `WatermarkConfig::layers`.+ Tournament,+ /// Non-distortionary tournament (continuous g + mandatory masking):+ /// key-averaged unbiased. See [`crate::tournament::tournament_nd_sample`].+ TournamentNd,+ /// Distortion-free Aaronson/Kuditipudi exponential-min.+ Gumbel,+}++/// The outcome of scoring a token sequence against a key.+#[derive(Clone, Copy, Debug)]+pub struct DetectionResult {+ pub scheme: Scheme,+ /// Number of positions that were watermarked (unmasked) and thus scored.+ /// Detection power grows with this, not with raw text length.+ pub scored_positions: usize,+ /// Raw aggregate statistic (ones-count for tournament; score-sum for gumbel).+ pub statistic: f64,+ /// Expected statistic under the null (no watermark).+ pub null_mean: f64,+ /// Standardized deviation from the null. Larger => stronger evidence.+ pub z_score: f64,+ /// Upper-tail p-value under the null. Small => likely watermarked. Floors at+ /// the smallest representable positive f64 for extreme z; use [`Self::log10_p`]+ /// for the true magnitude.+ pub p_value: f64,+ /// `log10(p_value)` computed stably even when `p_value` underflows to 0.+ pub log10_p: f64,+}++impl DetectionResult {+ /// A convenience verdict at a chosen false-positive rate `alpha`+ /// (e.g. `1e-6`). Returns `true` if the evidence clears the bar.+ pub fn is_watermarked(&self, alpha: f64) -> bool {+ self.log10_p <= alpha.log10()+ }+}++/// Detect using the tournament scheme. `cfg.layers` is the tournament depth `d`.+pub fn detect_tournament(tokens: &[u32], cfg: WatermarkConfig) -> DetectionResult {+ let d = cfg.layers.max(1);+ let mut tracker = ContextTracker::new(cfg);+ let mut ones: u64 = 0;+ let mut scored: usize = 0;+ for &tok in tokens {+ let ps = tracker.peek();+ if ps.watermarked {+ for layer in 1..=d {+ if g_bit(ps.seed, tok, layer) {+ ones += 1;+ }+ }+ scored += 1;+ }+ tracker.advance(ps, tok);+ }+ let n = (scored as u64 * d as u64) as f64; // total Bernoulli trials+ let null_mean = 0.5 * n;+ let std = (0.25 * n).sqrt(); // Binomial(N, Β½) sd = sqrt(N/4)+ let z = if std > 0.0 { (ones as f64 - null_mean) / std } else { 0.0 };+ let (p, lp) = normal_upper_tail(z);+ DetectionResult {+ scheme: Scheme::Tournament,+ scored_positions: scored,+ statistic: ones as f64,+ null_mean,+ z_score: z,+ p_value: p,+ log10_p: lp,+ }+}++/// Detect using the non-distortionary tournament (continuous g). Each+/// watermarked position contributes `d` terms `g_unit(seed, tok, β) - 0.5`,+/// mean 0 and variance `1/12` under the null; a winner's g-values skew high+/// (`E[g_unit] = 2/3` per won layer). Statistic standardized to a normal tail.+pub fn detect_tournament_nd(tokens: &[u32], cfg: WatermarkConfig) -> DetectionResult {+ let d = cfg.layers.max(1);+ let mut tracker = ContextTracker::new(cfg);+ let mut sum = 0.0f64;+ let mut scored: usize = 0;+ for &tok in tokens {+ let ps = tracker.peek();+ if ps.watermarked {+ for layer in 1..=d {+ sum += crate::hash::g_unit(ps.seed, tok, layer) - 0.5;+ }+ scored += 1;+ }+ tracker.advance(ps, tok);+ }+ let n = (scored as u64 * d as u64) as f64; // total uniform terms+ let std = (n / 12.0).sqrt(); // Var(U(0,1)) = 1/12+ let z = if std > 0.0 { sum / std } else { 0.0 };+ let (p, lp) = normal_upper_tail(z);+ DetectionResult {+ scheme: Scheme::TournamentNd,+ scored_positions: scored,+ statistic: sum,+ null_mean: 0.0,+ z_score: z,+ p_value: p,+ log10_p: lp,+ }+}++/// Detect using the distortion-free Gumbel scheme.+pub fn detect_gumbel(tokens: &[u32], cfg: WatermarkConfig) -> DetectionResult {+ let mut tracker = ContextTracker::new(cfg);+ let mut sum = 0.0f64;+ let mut scored: usize = 0;+ for &tok in tokens {+ let ps = tracker.peek();+ if ps.watermarked {+ sum += score_term(ps.seed, tok);+ scored += 1;+ }+ tracker.advance(ps, tok);+ }+ let n = scored as f64;+ // Sum of n i.i.d. Exp(1) has mean n, variance n; normal approx for the tail.+ let std = n.sqrt();+ let z = if std > 0.0 { (sum - n) / std } else { 0.0 };+ let (p, lp) = normal_upper_tail(z);+ DetectionResult {+ scheme: Scheme::Gumbel,+ scored_positions: scored,+ statistic: sum,+ null_mean: n,+ z_score: z,+ p_value: p,+ log10_p: lp,+ }+}++/// Complementary error function (Numerical Recipes `erfcc`): fractional error+/// < 1.2e-7 everywhere, and β crucially β stays accurate for large `x` where+/// `1 - erf(x)` would catastrophically cancel. Returns tiny positive values+/// rather than underflowing prematurely.+fn erfc(x: f64) -> f64 {+ let z = x.abs();+ let t = 1.0 / (1.0 + 0.5 * z);+ let ans = t+ * (-z * z - 1.265_512_23+ + t * (1.000_023_68+ + t * (0.374_091_96+ + t * (0.096_784_18+ + t * (-0.186_288_06+ + t * (0.278_868_07+ + t * (-1.135_203_98+ + t * (1.488_515_87+ + t * (-0.822_152_23 + t * 0.170_872_77)))))))))+ .exp();+ if x >= 0.0 {+ ans+ } else {+ 2.0 - ans+ }+}++/// Upper-tail probability `Q(z) = P(Z > z)` for standard normal, returned as+/// `(p_value, log10_p)`. For large `z` the p-value underflows to 0.0, so+/// `log10_p` is computed from the asymptotic tail+/// `ln Q(z) β -zΒ²/2 - ln(z) - Β½ln(2Ο)` to preserve the true magnitude.+pub(crate) fn normal_upper_tail(z: f64) -> (f64, f64) {+ let p = 0.5 * erfc(z / core::f64::consts::SQRT_2);+ if p > 0.0 && p.is_finite() {+ (p, p.log10())+ } else if z <= 0.0 {+ (0.5, 0.5f64.log10())+ } else {+ // Asymptotic log tail (natural log), converted to log10.+ let ln_q = -0.5 * z * z - z.ln() - 0.5 * (2.0 * core::f64::consts::PI).ln();+ (0.0, ln_q / core::f64::consts::LN_10)+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::hash::WatermarkKey;++ #[test]+ fn erfc_matches_known_values() {+ assert!((erfc(0.0) - 1.0).abs() < 1e-6);+ assert!((erfc(1.0) - 0.157_299_2).abs() < 1e-5);+ assert!(erfc(10.0) > 0.0 && erfc(10.0) < 1e-40); // stays positive & tiny+ }++ #[test]+ fn null_text_is_not_flagged() {+ // A deterministic pseudo-random token stream that never used the key must+ // score near z=0 (p ~ 0.5), not trip the detector.+ let cfg = WatermarkConfig::new(WatermarkKey(0xABCD)).with_layers(4);+ let tokens: Vec<u32> = (0..500u32).map(|i| crate::hash::mix64(i as u64) as u32 % 1000).collect();+ let r = detect_tournament(&tokens, cfg);+ assert!(r.z_score.abs() < 4.0, "null text spuriously flagged: z={}", r.z_score);+ assert!(!r.is_watermarked(1e-6), "false positive on null text");+ }+}diff --git a/v3/crates/ruflo-watermark/src/evolve.rs b/v3/crates/ruflo-watermark/src/evolve.rsnew file mode 100644index 0000000000..b7ba040c6e--- /dev/null+++ b/v3/crates/ruflo-watermark/src/evolve.rs@@ -0,0 +1,248 @@+//! Darwin/flywheel-style bounded tuner for the indel-robust alignment detector.+//!+//! ## Why in-crate, not `metaharness-darwin evolve`+//!+//! `@metaharness/darwin evolve` evolves *its own* synthetic 7-surface harness+//! and scores it by a target repo's test command; it cannot optimize this+//! crate's [`AlignParams`]. Shelling out to it would evolve the wrong thing+//! (NO SILENT SUBSTITUTION). So we apply the Darwin + flywheel *methodology*+//! where it actually fits:+//!+//! - **Frozen fitness** declared before the run (separation margin on a held-out+//! indel benchmark).+//! - **Bounded** generations Γ children (no unbounded search).+//! - **Retained lineage**: every candidate's receipt is kept, failures included,+//! so a future run does not rediscover a dead direction.+//! - **No auto-promotion**: returns the best candidate + full evidence; wiring it+//! in as the default is a separate, human decision.+//!+//! ## Fitness+//!+//! `margin = mean(z over watermarked-then-attacked cases) β max(z over null+//! cases)`. Rewards recovering signal after indel attacks while penalizing any+//! null case that scores high (false-positive control). Deterministic given the+//! benchmark seed β reproducible, no wall-clock.++use crate::align::{detect_gumbel_aligned, detect_gumbel_selfsync, AlignParams};+use crate::context::WatermarkConfig;+use crate::hash::mix64;+use crate::robustness::{attack_delete, attack_substitute};+use crate::{Scheme, Watermarker};++/// A frozen benchmark: watermarked-then-indel-attacked positives and null+/// negatives. Built once, reused across all candidates (fair comparison).+pub struct IndelBenchmark {+ positives: Vec<Vec<u32>>,+ negatives: Vec<Vec<u32>>,+ cfg: WatermarkConfig,+}++impl IndelBenchmark {+ /// Build the benchmark. `delete_rates` are the indel strengths sampled for+ /// positives; negatives are null streams over the same vocab. Deterministic.+ pub fn build(+ cfg: WatermarkConfig,+ vocab: u32,+ stream_len: usize,+ streams: usize,+ delete_rates: &[f64],+ seed: u64,+ ) -> Self {+ let tokens: Vec<u32> = (0..vocab).collect();+ let probs = vec![1.0f32 / vocab as f32; vocab as usize];+ let mut positives = Vec::with_capacity(streams);+ let mut negatives = Vec::with_capacity(streams);++ for s in 0..streams {+ // Positive: fresh watermarked stream, then a mixed indel+sub attack.+ let mut wm = Watermarker::new(cfg, Scheme::Gumbel);+ let clean: Vec<u32> = (0..stream_len).map(|_| tokens[wm.step(&tokens, &probs)]).collect();+ let rate = delete_rates[s % delete_rates.len()];+ let aseed = mix64(seed ^ s as u64 ^ 0x0DE1);+ let deleted = attack_delete(&clean, rate, aseed);+ // A light substitution on top, so the tuner isn't overfit to pure deletion.+ let attacked = attack_substitute(&deleted, rate * 0.5, vocab, mix64(aseed));+ positives.push(attacked);++ // Negative: null stream that never used the key.+ let nseed = mix64(seed ^ s as u64 ^ 0x0FF);+ let null: Vec<u32> = (0..stream_len)+ .map(|i| (mix64(nseed ^ i as u64) % vocab as u64) as u32)+ .collect();+ negatives.push(null);+ }+ IndelBenchmark { positives, negatives, cfg }+ }++ /// The frozen fitness for a candidate parameter set. Higher is better.+ pub fn fitness(&self, params: AlignParams) -> Receipt {+ self.score_with(|t| detect_gumbel_aligned(t, self.cfg, params).z_score, Some(params))+ }++ /// The self-sync baseline (parameter-free) scored on the SAME frozen cases β+ /// the honest reference the tuner must beat to justify the alignment layer.+ /// A frequent, legitimate outcome: self-sync already dominates and the+ /// evolution's evidence says so (a useful negative result).+ pub fn selfsync_reference(&self) -> Receipt {+ self.score_with(|t| detect_gumbel_selfsync(t, self.cfg).z_score, None)+ }++ fn score_with(&self, mut z: impl FnMut(&[u32]) -> f64, params: Option<AlignParams>) -> Receipt {+ let pos_mean = self.positives.iter().map(|t| z(t)).sum::<f64>()+ / self.positives.len().max(1) as f64;+ let neg_max = self.negatives.iter().map(|t| z(t)).fold(f64::MIN, f64::max);+ Receipt {+ params: params.unwrap_or(AlignParams::default()),+ pos_mean_z: pos_mean,+ neg_max_z: neg_max,+ margin: pos_mean - neg_max,+ }+ }+}++/// One candidate's evaluation evidence. Retained for the whole run (lineage).+#[derive(Clone, Copy, Debug)]+pub struct Receipt {+ pub params: AlignParams,+ pub pos_mean_z: f64,+ pub neg_max_z: f64,+ /// Frozen fitness: mean positive z minus worst null z.+ pub margin: f64,+}++/// Bounded-evolution budget. Kept small by default β this is tuning, not search.+#[derive(Clone, Copy, Debug)]+pub struct Budget {+ pub generations: u32,+ pub children: u32,+ pub seed: u64,+}++impl Default for Budget {+ fn default() -> Self {+ Budget { generations: 4, children: 6, seed: 0 }+ }+}++/// The outcome: the best alignment params found, the default-params baseline,+/// the parameter-free self-sync reference, and the full evaluated lineage+/// (evidence). Promotion β making `best` the default detector β is the caller's+/// decision, never automatic. `beats_selfsync()` reports the honest verdict.+pub struct EvolutionResult {+ pub best: Receipt,+ pub baseline: Receipt,+ pub selfsync: Receipt,+ pub lineage: Vec<Receipt>,+}++impl EvolutionResult {+ /// **In-sample** verdict: whether the selected params beat self-sync on the+ /// SEARCH benchmark. This is a selection-biased point estimate β `best` was+ /// chosen as the max-margin candidate over many children on one benchmark+ /// realization, so `best.margin` is optimistically inflated (winner's curse)+ /// and this comparison is NOT an error-controlled test. Use+ /// [`EvolutionResult::validate_on`] with a held-out benchmark for the honest+ /// verdict. (ADR-384 Β§Formal Properties: the rigorous gate is a held-out+ /// re-evaluation + a permutation/wrong-key null on the margin.)+ pub fn beats_selfsync(&self) -> bool {+ self.best.margin > self.selfsync.margin+ }++ /// **De-biased** verdict: re-evaluate the *already-selected* `best.params`+ /// (and self-sync) on an independent, held-out benchmark the search never+ /// saw. Because the params are fixed before this evaluation, the held-out+ /// margins carry no selection bias, so `beats` here is the trustworthy call.+ /// Returns `(best_holdout, selfsync_holdout, beats)`.+ pub fn validate_on(&self, holdout: &IndelBenchmark) -> (Receipt, Receipt, bool) {+ let best_h = holdout.fitness(self.best.params);+ let ss_h = holdout.selfsync_reference();+ let beats = best_h.margin > ss_h.margin;+ (best_h, ss_h, beats)+ }+}++#[inline]+fn u01(seed: u64, i: u64) -> f64 {+ (mix64(seed ^ i.wrapping_mul(0x9E37_79B9_7F4A_7C15)) >> 11) as f64 * (1.0 / (1u64 << 53) as f64)+}++/// Mutate a parent's params deterministically from `(seed, gen, child)`.+fn mutate(parent: AlignParams, seed: u64, gen: u32, child: u32) -> AlignParams {+ let base = mix64(seed ^ ((gen as u64) << 32) ^ child as u64);+ let d_band = (u01(base, 1) * 7.0) as i64 - 3; // -3..=3+ let band = (parent.band as i64 + d_band).clamp(1, 32) as usize;+ let d_gap = (u01(base, 2) - 0.5) * 0.8; // Β±0.4+ let gap_penalty = (parent.gap_penalty + d_gap).clamp(0.05, 3.0);+ let d_rep = (u01(base, 3) * 17.0) as i64 - 8; // -8..=8+ let null_replays = (parent.null_replays as i64 + d_rep).clamp(8, 48) as u32;+ AlignParams { band, gap_penalty, null_replays }+}++/// Evolve [`AlignParams`] against a frozen benchmark. Bounded, deterministic,+/// lineage-retaining, no auto-promotion.+pub fn evolve_align_params(bench: &IndelBenchmark, budget: Budget) -> EvolutionResult {+ let baseline = bench.fitness(AlignParams::default());+ let mut lineage = vec![baseline];+ let mut best = baseline;+ let mut parent = baseline.params;++ for gen in 1..=budget.generations {+ let mut gen_best = best;+ for child in 0..budget.children {+ let cand = mutate(parent, budget.seed, gen, child);+ let r = bench.fitness(cand);+ lineage.push(r); // retain every candidate, winners and losers+ if r.margin > gen_best.margin {+ gen_best = r;+ }+ }+ // Elitism: the parent of the next generation is the best-so-far.+ if gen_best.margin > best.margin {+ best = gen_best;+ }+ parent = best.params;+ }++ let selfsync = bench.selfsync_reference();+ EvolutionResult { best, baseline, selfsync, lineage }+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::hash::WatermarkKey;++ #[test]+ fn tuning_does_not_regress_the_baseline() {+ // The evolved best must be at least as good as the default params on the+ // frozen benchmark (elitism guarantees this) β and the lineage keeps+ // every candidate as evidence.+ let cfg = WatermarkConfig::new(WatermarkKey::from_bytes(b"tune")).with_layers(1);+ let bench = IndelBenchmark::build(cfg, 128, 600, 4, &[0.1, 0.2, 0.3], 0xABCD);+ let result = evolve_align_params(&bench, Budget { generations: 3, children: 5, seed: 1 });++ assert!(result.best.margin >= result.baseline.margin - 1e-9, "evolution regressed baseline");+ assert!(result.lineage.len() >= 1 + 3 * 5, "lineage not fully retained");+ // The tuner should keep null false-positives controlled.+ assert!(result.best.neg_max_z < 4.0, "tuned params allow null false-positive: {}", result.best.neg_max_z);+ // The self-sync reference is computed so the verdict is honest either way.+ assert!(result.selfsync.pos_mean_z > 0.0, "self-sync reference not evaluated");+ // Elitism holds; whether alignment beats self-sync is reported, not assumed.+ let _ = result.beats_selfsync();++ // De-biased verdict: re-evaluate the SELECTED params on an independent+ // held-out benchmark (different seed). The held-out margin removes the+ // winner's-curse inflation; the in-sample best.margin should be >= it.+ let holdout = IndelBenchmark::build(cfg, 128, 600, 4, &[0.1, 0.2, 0.3], 0x1111_2222);+ let (best_h, ss_h, _beats) = result.validate_on(&holdout);+ assert!(best_h.margin.is_finite() && ss_h.margin.is_finite());+ assert!(+ result.best.margin >= best_h.margin - 3.0,+ "held-out margin wildly exceeds in-sample β benchmark mismatch: {} vs {}",+ result.best.margin,+ best_h.margin+ );+ // Held-out null control still holds for the selected params.+ assert!(best_h.neg_max_z < 4.5, "held-out null false-positive: {}", best_h.neg_max_z);+ }+}diff --git a/v3/crates/ruflo-watermark/src/gumbel.rs b/v3/crates/ruflo-watermark/src/gumbel.rsnew file mode 100644index 0000000000..29d7dbbe55--- /dev/null+++ b/v3/crates/ruflo-watermark/src/gumbel.rs@@ -0,0 +1,109 @@+//! Provably distortion-free watermarking β the Aaronson (2022) exponential-min+//! scheme, also the basis of Kuditipudi et al. (2024) "Robust distortion-free+//! watermarks for language models".+//!+//! Unlike the tournament (which biases the distribution slightly), this scheme+//! samples *exactly* from the model distribution `p` β the marginal token+//! distribution is provably unchanged β while still leaving a key-detectable+//! signal. It is the right choice when zero distortion is a hard requirement.+//!+//! **Sampling.** For each candidate `i`, draw a uniform `u_i = g_unit(seed, i)`.+//! Emit `argmax_i u_i^{1/p_i}`. Equivalently (and how we compute it, avoiding+//! `powf`): emit `argmin_i (-ln u_i) / p_i`. Since `-ln u_i ~ Exp(1)`, the term+//! `(-ln u_i)/p_i ~ Exp(p_i)`, and the index of the minimum of independent+//! `Exp(p_i)` is `j` with probability `p_j / Ξ£ p = p_j`. Hence: distortion-free.+//!+//! **Detection.** The emitted token's `u_{x_t}` is stochastically *larger* than+//! a fresh uniform. The per-token statistic `-ln(1 - u_{x_t})` is `Exp(1)` under+//! the null (mean 1) but has mean `> 1` under the watermark. Summed over tokens+//! it is a clean Gamma-distributed detector (see [`crate::detect`]).++use crate::hash::g_unit;++/// Emit one watermarked token index at a position with random `seed`, using the+/// distortion-free exponential-min rule. `tokens[i]` is candidate `i`'s vocab id+/// and `probs[i]` its probability (parallel slices). Returns an index into+/// `tokens`/`probs`. The uniform is keyed on the **token id** so the detector,+/// which sees only emitted token ids, reproduces it. Zero-prob tokens are skipped.+pub fn gumbel_sample(tokens: &[u32], probs: &[f32], seed: u64) -> usize {+ debug_assert_eq!(tokens.len(), probs.len());+ let mut best = 0usize;+ let mut best_key = f64::INFINITY; // minimise (-ln u)/p+ for (i, (&tok, &p)) in tokens.iter().zip(probs.iter()).enumerate() {+ if p <= 0.0 {+ continue;+ }+ let u = g_unit(seed, tok, 0).max(f64::MIN_POSITIVE);+ let key = -u.ln() / p as f64;+ if key < best_key {+ best_key = key;+ best = i;+ }+ }+ best+}++/// The per-token detection contribution for a **token id** at `seed`:+/// `-ln(1 - u)`. Exposed so the detector can score directly from emitted token+/// ids without the candidate set.+#[inline]+pub fn score_term(seed: u64, token: u32) -> f64 {+ let u = g_unit(seed, token, 0).min(1.0 - f64::MIN_POSITIVE);+ -(1.0 - u).ln()+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::hash::{context_seed, WatermarkKey};++ fn ids(n: usize) -> Vec<u32> {+ (0..n as u32).collect()+ }++ #[test]+ fn is_distortion_free() {+ // The KEY property: marginal token frequencies must match p *exactly* in+ // expectation, across independent contexts. Tighter tolerance than the+ // tournament because this scheme is provably unbiased.+ let probs = [0.6f32, 0.25, 0.15];+ let tok = ids(3);+ let mut counts = [0usize; 3];+ let trials = 200_000u32;+ for c in 0..trials {+ let seed = context_seed(WatermarkKey(3), &[c, c ^ 0x5555]);+ counts[gumbel_sample(&tok, &probs, seed)] += 1;+ }+ let f0 = counts[0] as f64 / trials as f64;+ let f1 = counts[1] as f64 / trials as f64;+ assert!((f0 - 0.6).abs() < 0.006, "p0 drift {f0}");+ assert!((f1 - 0.25).abs() < 0.006, "p1 drift {f1}");+ }++ #[test]+ fn never_emits_zero_prob_token() {+ let probs = [0.0f32, 1.0, 0.0];+ let tok = ids(3);+ for c in 0..5000u32 {+ let seed = context_seed(WatermarkKey(1), &[c]);+ assert_eq!(gumbel_sample(&tok, &probs, seed), 1);+ }+ }++ #[test]+ fn chosen_token_has_elevated_score_term() {+ // Averaged over positions, the emitted token's score term exceeds the+ // null mean of 1.0 β this is what detection exploits.+ let probs = [0.5f32, 0.5];+ let tok = ids(2);+ let mut sum = 0.0;+ let trials = 40_000u32;+ for c in 0..trials {+ let seed = context_seed(WatermarkKey(2), &[c]);+ let idx = gumbel_sample(&tok, &probs, seed);+ sum += score_term(seed, tok[idx]);+ }+ let mean = sum / trials as f64;+ assert!(mean > 1.05, "watermark score term not elevated: {mean}");+ }+}diff --git a/v3/crates/ruflo-watermark/src/hash.rs b/v3/crates/ruflo-watermark/src/hash.rsnew file mode 100644index 0000000000..6d6530df2f--- /dev/null+++ b/v3/crates/ruflo-watermark/src/hash.rs@@ -0,0 +1,138 @@+//! Keyed pseudo-random function (PRF) that produces the watermark's *g-values*.+//!+//! In the SynthID-Text / Aaronson family, the watermark never invents a token+//! the model wouldn't have picked β it only changes the *source of randomness*+//! used to break ties among plausible tokens (the "digits of pi" analogy). This+//! module is that source: a fast, well-mixed keyed hash mapping+//! `(secret_key, context, token_id, layer)` to a uniform value.+//!+//! Two outputs are exposed:+//! - [`g_unit`]: a uniform `f64` in `[0, 1)` β used by the distortion-free+//! Gumbel scheme and by weighted detectors.+//! - [`g_bit`]: a uniform `bool` (fair coin) β used by SynthID Tournament layers.+//!+//! The mixing core is a 64-bit finalizer of the SplitMix64 / MurmurHash3+//! avalanche family: cheap (a few multiplies + xors), no table lookups, and+//! statistically uniform enough that `E[g_unit] = 0.5` on unwatermarked token+//! streams β the property detection relies on.++/// A secret watermarking key. Carries NO user-identifying information; it only+/// selects which pseudo-random stream the watermark rides on.+#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub struct WatermarkKey(pub u64);++impl WatermarkKey {+ /// Derive a key from arbitrary key material (e.g. a hex secret) by mixing+ /// its bytes. Deterministic; the same material always yields the same key.+ pub fn from_bytes(material: &[u8]) -> Self {+ let mut acc: u64 = 0x9E37_79B9_7F4A_7C15; // golden-ratio odd constant+ for &b in material {+ acc = mix64(acc ^ (b as u64).wrapping_add(0x0100_0000_01B3));+ }+ WatermarkKey(mix64(acc))+ }+}++/// SplitMix64 finalizer β a bijective avalanche mixer. Every input bit affects+/// every output bit; distinct inputs are statistically independent outputs.+#[inline(always)]+pub fn mix64(mut z: u64) -> u64 {+ z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);+ z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);+ z ^ (z >> 31)+}++/// Fold a context (the preceding `H` token ids) plus the secret key into a+/// single 64-bit seed `r`. This is the watermark's per-position randomness+/// source: the same context+key always produces the same `r`, which is exactly+/// what lets a detector recompute the stream without the model.+#[inline]+pub fn context_seed(key: WatermarkKey, context: &[u32]) -> u64 {+ let mut acc = key.0 ^ 0xD1B5_4A32_D192_ED03;+ for &tok in context {+ acc = mix64(acc.rotate_left(13) ^ (tok as u64).wrapping_mul(0x9E37_79B9_7F4A_7C15));+ }+ mix64(acc)+}++/// Raw 64-bit g-value for a `(seed, token, layer)` triple. `layer` selects an+/// independent tournament round (SynthID uses `m` layers); pass `0` for+/// single-layer schemes.+#[inline(always)]+pub fn g_raw(seed: u64, token: u32, layer: u32) -> u64 {+ // Distinct primes per field so token/layer/seed can't alias each other.+ let a = seed ^ (token as u64).wrapping_mul(0xFF51_AFD7_ED55_8CCD);+ let b = a.rotate_left(29) ^ (layer as u64).wrapping_mul(0xC4CE_B9FE_1A85_EC53);+ mix64(b)+}++/// Uniform `f64` in `[0, 1)` for `(seed, token, layer)`. Uses the top 53 bits so+/// the result is a uniformly-spaced dyadic rational (full f64 mantissa).+#[inline(always)]+pub fn g_unit(seed: u64, token: u32, layer: u32) -> f64 {+ (g_raw(seed, token, layer) >> 11) as f64 * (1.0 / (1u64 << 53) as f64)+}++/// Fair-coin g-value (`{0,1}`) for a SynthID tournament layer. Uses the top bit+/// of the mixed value, which is unbiased.+#[inline(always)]+pub fn g_bit(seed: u64, token: u32, layer: u32) -> bool {+ (g_raw(seed, token, layer) >> 63) == 1+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn g_bit_is_a_fair_coin() {+ // Over many tokens, P(g_bit = 1) must be ~0.5 β the null hypothesis the+ // detector tests against. A biased PRF would silently break detection.+ let seed = context_seed(WatermarkKey(42), &[1, 2, 3]);+ let ones = (0u32..100_000).filter(|&t| g_bit(seed, t, 0)).count();+ let frac = ones as f64 / 100_000.0;+ assert!((frac - 0.5).abs() < 0.01, "g_bit bias too large: {frac}");+ }++ #[test]+ fn g_unit_is_uniform_mean_half() {+ let seed = context_seed(WatermarkKey(7), &[9, 9, 9]);+ let sum: f64 = (0u32..100_000).map(|t| g_unit(seed, t, 0)).sum();+ let mean = sum / 100_000.0;+ assert!((mean - 0.5).abs() < 0.01, "g_unit mean off: {mean}");+ }++ #[test]+ fn layers_are_independent() {+ // Two tournament layers must not correlate, else stacking them adds no+ // detection power. Check the fraction where layer0 == layer1 is ~0.5.+ let seed = context_seed(WatermarkKey(1), &[5]);+ let agree = (0u32..100_000)+ .filter(|&t| g_bit(seed, t, 0) == g_bit(seed, t, 1))+ .count();+ let frac = agree as f64 / 100_000.0;+ assert!((frac - 0.5).abs() < 0.01, "layers correlated: {frac}");+ }++ #[test]+ fn context_changes_stream() {+ // Different preceding context => different randomness (so the same token+ // is watermarked differently in different places β the non-bias claim).+ let s1 = context_seed(WatermarkKey(1), &[1, 2, 3]);+ let s2 = context_seed(WatermarkKey(1), &[1, 2, 4]);+ assert_ne!(s1, s2);+ assert_ne!(g_unit(s1, 100, 0), g_unit(s2, 100, 0));+ }++ #[test]+ fn key_from_bytes_deterministic() {+ assert_eq!(+ WatermarkKey::from_bytes(b"8F3A91C7"),+ WatermarkKey::from_bytes(b"8F3A91C7")+ );+ assert_ne!(+ WatermarkKey::from_bytes(b"8F3A91C7"),+ WatermarkKey::from_bytes(b"8F3A91C8")+ );+ }+}diff --git a/v3/crates/ruflo-watermark/src/lib.rs b/v3/crates/ruflo-watermark/src/lib.rsnew file mode 100644index 0000000000..47d2f74f92--- /dev/null+++ b/v3/crates/ruflo-watermark/src/lib.rs@@ -0,0 +1,190 @@+//! # ruflo-watermark+//!+//! High-speed LLM **text watermarking** (generation + detection) in the+//! SynthID-Text / Aaronson family, with an optional WASM build and a defensive+//! robustness-evaluation harness.+//!+//! The watermark never invents a token the model would not have produced. It+//! only changes the *source of randomness* used to break ties among plausible+//! tokens β the "digits of pi" analogy from Anthropic's explainer. A holder of+//! the secret key can then test whether a token sequence rode that stream and+//! assign a probability that a keyed model produced it.+//!+//! Two schemes, sharing one keyed PRF ([`hash`]) and context machinery+//! ([`context`]):+//!+//! - [`Scheme::Tournament`] β SynthID-Text tournament sampling (Dathathri et+//! al., *Nature* 2024). Strong, mildly distortionary; strength scales with the+//! tournament depth.+//! - [`Scheme::Gumbel`] β the Aaronson (2022) / Kuditipudi et al. (2024)+//! exponential-min rule. Provably distortion-free (the marginal token+//! distribution is unchanged).+//!+//! ## Boundary+//!+//! This crate does not run an LLM. At each step the caller supplies the model's+//! candidate token ids and their probabilities (typically a top-k slice); the+//! watermarker selects which candidate to emit. This matches the deployment+//! shape: logits in, watermarked sample out, no extra tokens, negligible cost.+//!+//! ```+//! use ruflo_watermark::{Watermarker, WatermarkConfig, WatermarkKey, Scheme,+//! detect_gumbel};+//!+//! let cfg = WatermarkConfig::new(WatermarkKey::from_bytes(b"8F3A91C7"));+//! let mut wm = Watermarker::new(cfg, Scheme::Gumbel);+//!+//! // Two equally-plausible candidates (token ids 40 and 41), as in the diagram.+//! let tokens = [40u32, 41];+//! let probs = [0.5f32, 0.5];+//! let emitted_index = wm.step(&tokens, &probs);+//! let _emitted_token = tokens[emitted_index];+//! ```++pub mod align;+pub mod bayes;+pub mod context;+pub mod detect;+pub mod evolve;+pub mod gumbel;+pub mod hash;+pub mod rng;+pub mod robustness;+pub mod tournament;+pub mod unmarked;++#[cfg(feature = "wasm")]+pub mod wasm;++pub use context::{ContextTracker, PositionSeed, WatermarkConfig};+pub use detect::{detect_gumbel, detect_tournament, detect_tournament_nd, DetectionResult, Scheme};+pub use hash::WatermarkKey;++/// A streaming watermarked sampler. Holds the rolling context so successive+/// [`Watermarker::step`] calls form one coherent watermarked sequence.+pub struct Watermarker {+ tracker: ContextTracker,+ scheme: Scheme,+ depth: u32,+}++impl Watermarker {+ /// Create a watermarker. For [`Scheme::Tournament`], `cfg.layers` is the+ /// tournament depth `d` (`2^d` candidate draws per step).+ pub fn new(cfg: WatermarkConfig, scheme: Scheme) -> Self {+ let depth = cfg.layers.max(1);+ Watermarker {+ tracker: ContextTracker::new(cfg),+ scheme,+ depth,+ }+ }++ /// Emit one token given the model's candidate `tokens` and their `probs`+ /// (parallel slices). Returns the index of the chosen candidate and advances+ /// the rolling context. If this position is masked (repeated context), the+ /// token is drawn from the unmodified distribution β no watermark β keeping+ /// the scheme distribution-preserving and detector-aligned.+ pub fn step(&mut self, tokens: &[u32], probs: &[f32]) -> usize {+ debug_assert_eq!(tokens.len(), probs.len());+ let ps = self.tracker.peek();+ let idx = if ps.watermarked {+ match self.scheme {+ Scheme::Tournament => {+ tournament::tournament_sample(tokens, probs, ps.seed, self.depth)+ }+ Scheme::TournamentNd => {+ tournament::tournament_nd_sample(tokens, probs, ps.seed, self.depth)+ }+ Scheme::Gumbel => gumbel::gumbel_sample(tokens, probs, ps.seed),+ }+ } else {+ // Masked: plain draw from p, no watermark bias.+ rng::sample_index(probs, ps.seed, 0)+ };+ self.tracker.advance(ps, tokens[idx]);+ idx+ }++ /// The emitted token ids so far are the caller's responsibility to collect;+ /// this exposes the config for a detector to be built with matching settings.+ pub fn config(&self) -> &WatermarkConfig {+ self.tracker.config()+ }+}++#[cfg(test)]+mod integration {+ use super::*;++ // End-to-end: generate a watermarked stream, then confirm the detector+ // flags it with overwhelming confidence while a null stream is not flagged.+ fn run_scheme(scheme: Scheme) -> (DetectionResult, DetectionResult) {+ let vocab = 128u32;+ let cfg = WatermarkConfig::new(WatermarkKey::from_bytes(b"secret")).with_layers(6);+ let tokens: Vec<u32> = (0..vocab).collect();+ let probs = vec![1.0f32 / vocab as f32; vocab as usize];++ let mut wm = Watermarker::new(cfg, scheme);+ let watermarked: Vec<u32> = (0..600).map(|_| tokens[wm.step(&tokens, &probs)]).collect();++ // A null stream: independent pseudo-random tokens, no key involved.+ let null: Vec<u32> = (0..600u32)+ .map(|i| (hash::mix64(i as u64 ^ 0xFEED) % vocab as u64) as u32)+ .collect();++ let detect = |t: &[u32]| match scheme {+ Scheme::Tournament => detect_tournament(t, cfg),+ Scheme::TournamentNd => detect_tournament_nd(t, cfg),+ Scheme::Gumbel => detect_gumbel(t, cfg),+ };+ (detect(&watermarked), detect(&null))+ }++ #[test]+ fn tournament_end_to_end() {+ let (wm, null) = run_scheme(Scheme::Tournament);+ assert!(wm.is_watermarked(1e-6), "watermarked text not detected: z={}", wm.z_score);+ assert!(!null.is_watermarked(1e-6), "null text false-positive: z={}", null.z_score);+ assert!(wm.z_score > null.z_score + 5.0);+ }++ #[test]+ fn gumbel_end_to_end() {+ let (wm, null) = run_scheme(Scheme::Gumbel);+ assert!(wm.is_watermarked(1e-6), "watermarked text not detected: z={}", wm.z_score);+ assert!(!null.is_watermarked(1e-6), "null text false-positive: z={}", null.z_score);+ assert!(wm.z_score > null.z_score + 5.0);+ }++ #[test]+ fn tournament_nd_end_to_end() {+ let vocab = 128u32;+ let cfg = WatermarkConfig::new(WatermarkKey::from_bytes(b"nd")).with_layers(6);+ let tokens: Vec<u32> = (0..vocab).collect();+ let probs = vec![1.0f32 / vocab as f32; vocab as usize];+ let mut wm = Watermarker::new(cfg, Scheme::TournamentNd);+ let watermarked: Vec<u32> = (0..600).map(|_| tokens[wm.step(&tokens, &probs)]).collect();+ let null: Vec<u32> = (0..600u32).map(|i| (hash::mix64(i as u64 ^ 0xBEEF) % vocab as u64) as u32).collect();+ let wm_r = detect_tournament_nd(&watermarked, cfg);+ let null_r = detect_tournament_nd(&null, cfg);+ assert!(wm_r.is_watermarked(1e-6), "TournamentNd not detected: z={}", wm_r.z_score);+ assert!(!null_r.is_watermarked(1e-6), "TournamentNd null false-positive: z={}", null_r.z_score);+ }++ #[test]+ fn wrong_key_does_not_detect() {+ // Detection with a DIFFERENT key must see nothing β the watermark is+ // key-specific (one provider's mark is invisible to another's detector).+ let vocab = 128u32;+ let gen_cfg = WatermarkConfig::new(WatermarkKey(1)).with_layers(6);+ let tokens: Vec<u32> = (0..vocab).collect();+ let probs = vec![1.0f32 / vocab as f32; vocab as usize];+ let mut wm = Watermarker::new(gen_cfg, Scheme::Gumbel);+ let stream: Vec<u32> = (0..600).map(|_| tokens[wm.step(&tokens, &probs)]).collect();++ let wrong_cfg = WatermarkConfig::new(WatermarkKey(2)).with_layers(6);+ let r = detect_gumbel(&stream, wrong_cfg);+ assert!(!r.is_watermarked(1e-6), "detected under the wrong key: z={}", r.z_score);+ }+}diff --git a/v3/crates/ruflo-watermark/src/rng.rs b/v3/crates/ruflo-watermark/src/rng.rsnew file mode 100644index 0000000000..c94cfb4372--- /dev/null+++ b/v3/crates/ruflo-watermark/src/rng.rs@@ -0,0 +1,76 @@+//! Deterministic categorical sampling from a candidate distribution.+//!+//! The watermark schemes need to draw tokens from the model's next-token+//! distribution using randomness that is (a) reproducible from `(seed, draw)` so+//! generation is deterministic given the key, and (b) *namespaced away* from the+//! g-values, so the base draw and the tournament/selection signal are+//! statistically independent. Both come from the same PRF ([`crate::hash`]) but+//! on disjoint `layer` namespaces.++use crate::hash::g_unit;++/// Layer namespace for base categorical draws, kept disjoint from tournament+/// g-value layers (which live in `0..m`) so a draw's randomness never aliases+/// the selection signal.+const RNG_LAYER_BASE: u32 = 0xF000_0000;++/// Draw one token index from `probs` (which must be finite, non-negative, and+/// sum to > 0) using the uniform derived from `(seed, draw_index)`. Inverse-CDF+/// over the candidate list; O(k) in the number of candidates.+///+/// Returns an index into `probs`, not a token id β the caller maps it back.+#[inline]+pub fn sample_index(probs: &[f32], seed: u64, draw_index: u32) -> usize {+ debug_assert!(!probs.is_empty());+ let total: f64 = probs.iter().map(|&p| p as f64).sum();+ let u = g_unit(seed, draw_index, RNG_LAYER_BASE) * total;+ let mut acc = 0.0f64;+ for (i, &p) in probs.iter().enumerate() {+ acc += p as f64;+ if u < acc {+ return i;+ }+ }+ probs.len() - 1 // floating-point slack: fall back to last candidate+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn respects_the_distribution() {+ // A candidate that owns 80% of the mass should be drawn ~80% of the time.+ let probs = [0.8f32, 0.1, 0.1];+ let mut counts = [0usize; 3];+ for d in 0..50_000u32 {+ counts[sample_index(&probs, 123, d)] += 1;+ }+ let frac0 = counts[0] as f64 / 50_000.0;+ assert!((frac0 - 0.8).abs() < 0.01, "top candidate frac {frac0}");+ }++ #[test]+ fn deterministic() {+ let probs = [0.5f32, 0.3, 0.2];+ assert_eq!(+ sample_index(&probs, 999, 4),+ sample_index(&probs, 999, 4)+ );+ }++ #[test]+ fn draws_are_independent() {+ // Consecutive draw indices must not correlate (else the tournament's+ // 2^d "independent" samples wouldn't be independent).+ let probs = [0.5f32, 0.5];+ let mut agree = 0;+ for d in (0..40_000u32).step_by(2) {+ if sample_index(&probs, 7, d) == sample_index(&probs, 7, d + 1) {+ agree += 1;+ }+ }+ let frac = agree as f64 / 20_000.0;+ assert!((frac - 0.5).abs() < 0.02, "adjacent draws correlated: {frac}");+ }+}diff --git a/v3/crates/ruflo-watermark/src/robustness.rs b/v3/crates/ruflo-watermark/src/robustness.rsnew file mode 100644index 0000000000..6f2824a3bb--- /dev/null+++ b/v3/crates/ruflo-watermark/src/robustness.rs@@ -0,0 +1,268 @@+//! Robustness evaluation harness β the *defensive* red-team half of the crate.+//!+//! Purpose and scope (read this before using it): this measures **how much a+//! watermark's detectability degrades under editing**, so a watermark designer+//! can quantify robustness and harden the scheme (larger context width, more+//! layers, better scorers). It is the watermarking analogue of the adversarial+//! robustness curves used throughout metaharness/redblue.+//!+//! It deliberately reports *detection statistics after an attack* β a robustness+//! curve β and operates on abstract token-id sequences. It is **not** a+//! text-laundering tool: it does not take natural-language text and hand back a+//! "cleaned" version with the mark stripped. The output is evidence about the+//! watermark, not a product for defeating provenance. Removing a watermark from+//! third-party AI text to pass it off as un-marked defeats the EU AI Act+//! transparency mechanism these watermarks exist to satisfy; that is not what+//! this harness is for and not something it is built to do.+//!+//! Attacks modeled (all deterministic given an `attack_seed`, for reproducible+//! curves): random token **substitution**, **deletion**, and contiguous-span+//! **resampling** (a stand-in for local paraphrase). Each returns the residual+//! detection result so you can plot detectability vs attack strength.++use crate::context::WatermarkConfig;+use crate::detect::{detect_gumbel, detect_tournament, DetectionResult, Scheme};+use crate::hash::mix64;++/// A single point on a robustness curve: the attack applied and the detection+/// result that survived it.+#[derive(Clone, Copy, Debug)]+pub struct RobustnessPoint {+ /// Fraction of tokens perturbed (0.0..=1.0).+ pub attack_strength: f64,+ /// Detection outcome on the attacked sequence.+ pub detection: DetectionResult,+}++/// Deterministic uniform in `[0,1)` from `(attack_seed, index)` β keeps attacks+/// reproducible so a robustness curve is a stable measurement, not a coin flip.+#[inline]+fn u01(attack_seed: u64, index: u64) -> f64 {+ (mix64(attack_seed ^ index.wrapping_mul(0x9E37_79B9_7F4A_7C15)) >> 11) as f64+ * (1.0 / (1u64 << 53) as f64)+}++#[inline]+fn rand_token(attack_seed: u64, index: u64, vocab: u32) -> u32 {+ (mix64(attack_seed ^ index ^ 0xDEAD_BEEF) % vocab as u64) as u32+}++/// Substitute each token independently with probability `rate`, replacing it+/// with a uniform random vocab token. The canonical watermark-robustness stress+/// test (mirrors "edit N% of the words").+pub fn attack_substitute(tokens: &[u32], rate: f64, vocab: u32, attack_seed: u64) -> Vec<u32> {+ tokens+ .iter()+ .enumerate()+ .map(|(i, &t)| {+ if u01(attack_seed, i as u64) < rate {+ rand_token(attack_seed, i as u64, vocab)+ } else {+ t+ }+ })+ .collect()+}++/// Delete each token independently with probability `rate`. Shifts all+/// downstream contexts β a harder attack because it desynchronizes the context+/// windows, not just individual g-values.+pub fn attack_delete(tokens: &[u32], rate: f64, attack_seed: u64) -> Vec<u32> {+ tokens+ .iter()+ .enumerate()+ .filter(|(i, _)| u01(attack_seed, *i as u64) >= rate)+ .map(|(_, &t)| t)+ .collect()+}++/// Resample a single contiguous span of length `span` starting at `start` with+/// fresh random tokens β a stand-in for locally paraphrasing one passage while+/// leaving the rest intact.+pub fn attack_resample_span(+ tokens: &[u32],+ start: usize,+ span: usize,+ vocab: u32,+ attack_seed: u64,+) -> Vec<u32> {+ let mut out = tokens.to_vec();+ let end = (start + span).min(out.len());+ for (i, slot) in out.iter_mut().enumerate().take(end).skip(start) {+ *slot = rand_token(attack_seed, i as u64, vocab);+ }+ out+}++/// Insert a random token after each position with probability `rate` β the+/// dual of deletion; also desynchronizes downstream contexts.+pub fn attack_insert(tokens: &[u32], rate: f64, vocab: u32, attack_seed: u64) -> Vec<u32> {+ let mut out = Vec::with_capacity(tokens.len() + tokens.len() / 4);+ for (i, &t) in tokens.iter().enumerate() {+ out.push(t);+ if u01(attack_seed ^ 0x1_0000, i as u64) < rate {+ out.push(rand_token(attack_seed ^ 0x2_0000, i as u64, vocab));+ }+ }+ out+}++/// Combined "paraphrase-like" attack: substitution + deletion + insertion at a+/// shared strength, the realistic mixed edit a light rewrite produces. Composed+/// in one pass over the buffer to keep it fast.+pub fn attack_paraphrase(tokens: &[u32], strength: f64, vocab: u32, attack_seed: u64) -> Vec<u32> {+ let subbed = attack_substitute(tokens, strength * 0.6, vocab, attack_seed);+ let deleted = attack_delete(&subbed, strength * 0.3, mix64(attack_seed));+ attack_insert(&deleted, strength * 0.3, vocab, mix64(mix64(attack_seed)))+}++/// **Adaptive worst-case attack** (the "ultra" part). Rather than editing+/// uniformly, spend a fixed edit budget on the positions that currently carry+/// the *most* watermark signal β the strongest robustness stress a bounded-+/// budget editor could apply. Reports the residual detection, i.e. the+/// worst-case detectability at that budget. Measurement only: it returns a+/// detection statistic, never a "cleaned" text for laundering.+pub fn adaptive_worst_case(+ tokens: &[u32],+ cfg: WatermarkConfig,+ scheme: Scheme,+ vocab: u32,+ budget_frac: f64,+ attack_seed: u64,+) -> DetectionResult {+ // Rank positions by their standalone contribution to the statistic, then+ // substitute the top `budget_frac` fraction. Uses per-position seeds from a+ // fresh context tracker so ranking matches what detection actually scores.+ let n = tokens.len();+ let budget = ((n as f64) * budget_frac).round() as usize;+ let mut contrib: Vec<(f64, usize)> = (0..n)+ .map(|i| {+ let start = i.saturating_sub(cfg.context_width);+ let seed = crate::hash::context_seed(cfg.key, &tokens[start..i]);+ let c = match scheme {+ Scheme::Gumbel => crate::gumbel::score_term(seed, tokens[i]),+ Scheme::Tournament => {+ let d = cfg.layers.max(1);+ (1..=d).filter(|&l| crate::hash::g_bit(seed, tokens[i], l)).count() as f64+ }+ Scheme::TournamentNd => {+ let d = cfg.layers.max(1);+ (1..=d).map(|l| crate::hash::g_unit(seed, tokens[i], l)).sum::<f64>()+ }+ };+ (c, i)+ })+ .collect();+ // Partial sort: highest-contribution positions first.+ contrib.sort_unstable_by(|a, b| b.0.partial_cmp(&a.0).unwrap_or(core::cmp::Ordering::Equal));+ let mut attacked = tokens.to_vec();+ for &(_, i) in contrib.iter().take(budget) {+ attacked[i] = rand_token(attack_seed, i as u64, vocab);+ }+ redetect(&attacked, cfg, scheme)+}++/// Re-detect after an attack, choosing the detector by `scheme`.+fn redetect(tokens: &[u32], cfg: WatermarkConfig, scheme: Scheme) -> DetectionResult {+ match scheme {+ Scheme::Tournament => detect_tournament(tokens, cfg),+ Scheme::TournamentNd => crate::detect::detect_tournament_nd(tokens, cfg),+ Scheme::Gumbel => detect_gumbel(tokens, cfg),+ }+}++/// Sweep substitution strength across `rates` and report the detectability+/// curve. This is the headline robustness measurement: at each edit rate, how+/// strong is the surviving evidence?+pub fn sweep_substitution(+ tokens: &[u32],+ cfg: WatermarkConfig,+ scheme: Scheme,+ vocab: u32,+ rates: &[f64],+ attack_seed: u64,+) -> Vec<RobustnessPoint> {+ rates+ .iter()+ .map(|&rate| {+ let attacked = attack_substitute(tokens, rate, vocab, attack_seed);+ RobustnessPoint {+ attack_strength: rate,+ detection: redetect(&attacked, cfg, scheme),+ }+ })+ .collect()+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::hash::WatermarkKey;+ use crate::Watermarker;++ // Build a watermarked stream over a small vocab with a flat-ish distribution+ // so the watermark has many low-stakes choices to ride.+ fn watermarked_stream(n: usize, scheme: Scheme) -> (Vec<u32>, WatermarkConfig, u32) {+ let vocab = 64u32;+ let cfg = WatermarkConfig::new(WatermarkKey(0x1234)).with_layers(5);+ let mut wm = Watermarker::new(cfg, scheme);+ let tokens: Vec<u32> = (0..vocab).collect();+ let probs = vec![1.0f32 / vocab as f32; vocab as usize];+ let out: Vec<u32> = (0..n).map(|_| tokens[wm.step(&tokens, &probs)]).collect();+ (out, cfg, vocab)+ }++ #[test]+ fn adaptive_attack_is_worse_than_uniform_at_equal_budget() {+ // The "ultra" robustness measurement: spending the SAME edit budget on+ // the highest-signal positions degrades detection more than spreading it+ // uniformly β the true worst-case robustness a bounded editor achieves.+ let (stream, cfg, vocab) = watermarked_stream(1200, Scheme::Gumbel);+ let budget = 0.2;+ let uniform = super::attack_substitute(&stream, budget, vocab, 0x51);+ let z_uniform = crate::detect::detect_gumbel(&uniform, cfg).z_score;+ let z_adaptive = super::adaptive_worst_case(&stream, cfg, Scheme::Gumbel, vocab, budget, 0x51).z_score;+ assert!(+ z_adaptive < z_uniform,+ "adaptive attack ({z_adaptive}) not worse than uniform ({z_uniform}) at equal budget"+ );+ }++ #[test]+ fn insertion_is_handled_and_degrades() {+ let (stream, cfg, vocab) = watermarked_stream(1000, Scheme::Gumbel);+ let clean = crate::detect::detect_gumbel(&stream, cfg).z_score;+ let inserted = super::attack_insert(&stream, 0.2, vocab, 0x99);+ // Position-locked detection under insertion; self-sync would recover more.+ let after = crate::detect::detect_gumbel(&inserted, cfg).z_score;+ assert!(after.is_finite() && after < clean, "insertion not measured: {clean} -> {after}");+ }++ #[test]+ fn detectability_decays_monotonically_with_attack() {+ let (stream, cfg, vocab) = watermarked_stream(800, Scheme::Tournament);+ let curve = sweep_substitution(+ &stream,+ cfg,+ Scheme::Tournament,+ vocab,+ &[0.0, 0.25, 0.5, 0.9],+ 0xA77,+ );+ // Clean text: strong evidence. Heavily edited: evidence collapses toward+ // the null. z must be (weakly) non-increasing across the sweep.+ assert!(curve[0].detection.z_score > 6.0, "clean stream too weak: z={}", curve[0].detection.z_score);+ for w in curve.windows(2) {+ assert!(+ w[1].detection.z_score <= w[0].detection.z_score + 1.5,+ "detectability did not degrade: {:?} -> {:?}",+ w[0].detection.z_score,+ w[1].detection.z_score+ );+ }+ assert!(+ curve.last().unwrap().detection.z_score < curve[0].detection.z_score,+ "90% edit left detection unchanged"+ );+ }+}diff --git a/v3/crates/ruflo-watermark/src/tournament.rs b/v3/crates/ruflo-watermark/src/tournament.rsnew file mode 100644index 0000000000..e139f9d748--- /dev/null+++ b/v3/crates/ruflo-watermark/src/tournament.rs@@ -0,0 +1,195 @@+//! SynthID-Text Tournament sampling (Dathathri et al., *Nature* 2024).+//!+//! This is the scheme the shared diagram illustrates: among *similarly+//! plausible* tokens, the secret key + preceding tokens (via the g-values)+//! decide which candidate is emitted. Concretely, at a watermarked position:+//!+//! 1. Draw `2^d` candidate tokens i.i.d. from the model distribution `p`+//! (`d` = tournament depth).+//! 2. Run a balanced single-elimination bracket of `d` rounds. In round `β`,+//! pair up survivors and keep whichever token has the larger `g_β` value.+//! 3. Emit the final winner.+//!+//! Because the `2^d` entrants are genuine i.i.d. draws from `p`, the emitted+//! token is always one the model itself would plausibly have produced β the+//! watermark never injects an out-of-distribution word (no "nubilous"). It only+//! biases *which* plausible candidate wins, in a way a detector holding the key+//! can recover: the winner's g-values are systematically high.+//!+//! **Strength vs cost.** Larger `d` => stronger per-token signal (winner is the+//! max over more competitors) at `2^d` sampling cost. `d = 3` (8 draws) is a+//! good default; the paper's regime lives around here for the distortionary+//! tournament.++use crate::hash::{g_bit, g_unit};+use crate::rng::sample_index;++/// Emit one watermarked token index at a position with random `seed`, using a+/// depth-`d` tournament. `tokens[i]` is the vocabulary id of candidate `i` and+/// `probs[i]` its model probability; the two slices are parallel. Returns an+/// index into `tokens`/`probs`.+///+/// g-values are keyed on the candidate's **token id** (`tokens[i]`), never its+/// position in the list β this is what lets the detector, which sees only the+/// emitted token id, recompute the exact same g-values without the candidate set.+///+/// `depth` is clamped to `1..=16` (2..=65536 candidates).+pub fn tournament_sample(tokens: &[u32], probs: &[f32], seed: u64, depth: u32) -> usize {+ debug_assert_eq!(tokens.len(), probs.len());+ let d = depth.clamp(1, 16);+ let n = 1usize << d;++ // Round 0: 2^d i.i.d. entrants from p. Store candidate *indices* into tokens.+ let mut bracket: Vec<usize> = (0..n as u32)+ .map(|draw| sample_index(probs, seed, draw))+ .collect();++ // Rounds 1..=d: pair adjacent survivors; keep the higher g_β (keyed on the+ // candidate's token id). Ties (both bits equal) keep the left entrant β a+ // fixed, detector-reproducible rule.+ let mut round = 1u32;+ while bracket.len() > 1 {+ let mut next = Vec::with_capacity(bracket.len() / 2);+ let mut i = 0;+ while i + 1 < bracket.len() {+ let a = bracket[i];+ let b = bracket[i + 1];+ let ga = g_bit(seed, tokens[a], round);+ let gb = g_bit(seed, tokens[b], round);+ next.push(if gb && !ga { b } else { a });+ i += 2;+ }+ if bracket.len() % 2 == 1 {+ next.push(bracket[bracket.len() - 1]);+ }+ bracket = next;+ round += 1;+ }+ bracket[0]+}++/// Non-distortionary tournament variant (`Scheme::TournamentNd`). Same balanced+/// bracket, but comparisons use the **continuous** g-value `g_unit` (finer than+/// the fair-coin `g_bit`) and this scheme relies on repeated-context masking+/// being ON (the default) to keep its distribution-preservation property on+/// repetitive text.+///+/// **Property (measured, not asserted from theory):** averaged over the key, the+/// emitted-token distribution matches `p` to within sampling noise (drift+/// < 0.3% at depths 1β5 in tests) β this is the SynthID-Text *non-distortionary*+/// configuration: key-averaged unbiased. Note this is weaker than the *per-key*+/// distortion-freeness of [`crate::gumbel`]; for a fixed key the tournament+/// still biases toward high-g tokens (that bias is exactly the watermark).+pub fn tournament_nd_sample(tokens: &[u32], probs: &[f32], seed: u64, depth: u32) -> usize {+ debug_assert_eq!(tokens.len(), probs.len());+ let d = depth.clamp(1, 16);+ let n = 1usize << d;+ let mut bracket: Vec<usize> = (0..n as u32).map(|draw| sample_index(probs, seed, draw)).collect();+ let mut round = 1u32;+ while bracket.len() > 1 {+ let mut next = Vec::with_capacity(bracket.len() / 2);+ let mut i = 0;+ while i + 1 < bracket.len() {+ let a = bracket[i];+ let b = bracket[i + 1];+ // Continuous g; higher wins. Ties (equal f64) keep the left entrant.+ let ga = g_unit(seed, tokens[a], round);+ let gb = g_unit(seed, tokens[b], round);+ next.push(if gb > ga { b } else { a });+ i += 2;+ }+ if bracket.len() % 2 == 1 {+ next.push(bracket[bracket.len() - 1]);+ }+ bracket = next;+ round += 1;+ }+ bracket[0]+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::hash::{context_seed, WatermarkKey};++ // Identity token map: candidate index i has token id i, so index == id.+ fn ids(n: usize) -> Vec<u32> {+ (0..n as u32).collect()+ }++ #[test]+ fn winner_is_always_a_plausible_candidate() {+ // The emitted index must be one p actually supports (non-zero prob),+ // never an injected out-of-distribution token.+ let probs = [0.0f32, 0.5, 0.5, 0.0];+ let tok = ids(4);+ let seed = context_seed(WatermarkKey(1), &[1, 2]);+ for _ in 0..1000 {+ let idx = tournament_sample(&tok, &probs, seed, 3);+ assert!(probs[idx] > 0.0, "emitted a zero-probability token");+ }+ }++ #[test]+ fn preserves_distribution_in_aggregate_over_contexts() {+ // Across many DISTINCT contexts (so g-values vary), the tournament winner+ // frequencies must track p β the watermark biases the *randomness source*+ // not the *distribution* (Anthropic's "no bias toward overcast" claim).+ let probs = [0.7f32, 0.2, 0.1];+ let tok = ids(3);+ let mut counts = [0usize; 3];+ let trials = 60_000u32;+ for c in 0..trials {+ let seed = context_seed(WatermarkKey(9), &[c, c.wrapping_mul(31)]);+ counts[tournament_sample(&tok, &probs, seed, 3)] += 1;+ }+ let frac0 = counts[0] as f64 / trials as f64;+ assert!((frac0 - 0.7).abs() < 0.06, "distribution drifted: {frac0}");+ }++ #[test]+ fn depth_clamps_to_valid_candidate() {+ let probs = [0.5f32, 0.5];+ let tok = ids(2);+ let idx = tournament_sample(&tok, &probs, 42, 0);+ assert!(idx < 2);+ }+}++#[cfg(test)]+mod nd_tests {+ use super::*;+ use crate::hash::{context_seed, WatermarkKey};++ #[test]+ fn nd_tournament_is_key_averaged_non_distortionary() {+ // The defining property: averaged over the key, the emitted distribution+ // matches p to within sampling noise, at every depth. sd for p0=0.7 over+ // 120k trials is ~0.0013, so a 3-sigma band is ~0.004.+ let probs = [0.7f32, 0.2, 0.1];+ let tok: Vec<u32> = (0..3).collect();+ let trials = 120_000u32;+ for depth in [1u32, 2, 3, 5] {+ let mut c = [0usize; 3];+ for k in 0..trials {+ let seed = context_seed(WatermarkKey(9), &[k, k.wrapping_mul(31)]);+ c[tournament_nd_sample(&tok, &probs, seed, depth)] += 1;+ }+ let f0 = c[0] as f64 / trials as f64;+ let f1 = c[1] as f64 / trials as f64;+ assert!((f0 - 0.7).abs() < 0.006, "depth {depth}: p0 drift {:+.4}", f0 - 0.7);+ assert!((f1 - 0.2).abs() < 0.006, "depth {depth}: p1 drift {:+.4}", f1 - 0.2);+ }+ }++ #[test]+ fn nd_winner_is_plausible() {+ let probs = [0.0f32, 0.5, 0.5, 0.0];+ let tok: Vec<u32> = (0..4).collect();+ let seed = context_seed(WatermarkKey(1), &[3]);+ for _ in 0..500 {+ let idx = tournament_nd_sample(&tok, &probs, seed, 4);+ assert!(probs[idx] > 0.0);+ }+ }+}diff --git a/v3/crates/ruflo-watermark/src/unmarked.rs b/v3/crates/ruflo-watermark/src/unmarked.rsnew file mode 100644index 0000000000..1ad085e1e6--- /dev/null+++ b/v3/crates/ruflo-watermark/src/unmarked.rs@@ -0,0 +1,393 @@+//! Authorized un-marked generation β the *legitimate* way to produce+//! un-watermarked output of your own model, without a laundering tool.+//!+//! ## Why this is not a watermark remover+//!+//! If you hold the key, you never need to *strip* a finished text β you either+//! don't apply the mark, or you regenerate from the same inputs with marking+//! off. Stripping the signal out of finished text is only necessary for content+//! you did NOT generate (someone else's mark), which is exactly the laundering+//! case. So this module **only generates**. It has no function that accepts an+//! existing token sequence and removes its watermark; it is therefore+//! structurally impossible to point at third-party marked text. Un-marked+//! generation here is plain categorical sampling β the watermark key is never+//! used, so the output carries no mark by construction.+//!+//! ## Governance, enforced by construction+//!+//! Exemption from *watermarking* is never exemption from *disclosure*. This path+//! makes that hard to violate:+//!+//! - **Authorization is unforgeable.** Un-marked generation requires an+//! [`AuthorizationGrant`] minted by the compliance key-custodian+//! ([`AuthorizationKey`], distinct from the watermark key) and bound to a+//! specific request + documented [`ExemptionReason`] + timestamp via a MAC.+//! A forged or mismatched grant is denied (and the denial is audited).+//! - **Disclosure is mandatory to finish.** An [`UnmarkedSession`] can only be+//! completed by supplying a [`ProvenanceDisclosure`] (a C2PA credential, an+//! explicit AI label, or an internal provenance-log id). You cannot cleanly+//! end an un-marked generation without declaring how it stays disclosed.+//! - **Silence is loud.** A session dropped without `finish` commits an+//! `AbandonedUndisclosed` audit record β an un-marked generation that never+//! declared disclosure is recorded as a compliance gap, never forgotten.+//!+//! Whether a given case is genuinely exempt under the EU AI Act is a legal+//! determination, not an engineering one. This builds the switch and its audit;+//! the policy of when to flip it belongs to compliance.++use crate::hash::mix64;+use crate::rng::sample_index;++/// Secret authorization key held by the compliance / key-custodian authority.+/// Gates WHETHER un-marked generation is permitted β distinct from the watermark+/// key (which governs how text is marked).+#[derive(Clone, Copy)]+pub struct AuthorizationKey(u64);++impl AuthorizationKey {+ pub fn from_bytes(material: &[u8]) -> Self {+ let mut acc = 0xC0FF_EE00_1234_5678u64;+ for &b in material {+ acc = mix64(acc ^ b as u64);+ }+ AuthorizationKey(mix64(acc))+ }+}++/// Errors from the governance path.+#[derive(Clone, Debug, PartialEq, Eq)]+pub enum PolicyError {+ /// The exemption reason was empty β every exemption must be documented.+ EmptyReason,+ /// The authorization grant did not verify against the authority key.+ Unauthorized,+ /// A provenance disclosure string was empty.+ EmptyDisclosure,+}++/// A documented, non-empty reason a generation is exempt from watermarking.+#[derive(Clone, Debug)]+pub struct ExemptionReason(String);++impl ExemptionReason {+ pub fn new(reason: impl Into<String>) -> Result<Self, PolicyError> {+ let r = reason.into();+ if r.trim().is_empty() {+ Err(PolicyError::EmptyReason)+ } else {+ Ok(ExemptionReason(r))+ }+ }+ pub fn as_str(&self) -> &str {+ &self.0+ }+ fn hash(&self) -> u64 {+ let mut acc = 0x1234_5678_9ABC_DEF0u64;+ for &b in self.0.as_bytes() {+ acc = mix64(acc ^ b as u64);+ }+ acc+ }+}++/// An unforgeable authorization to un-mark exactly one request. Minted by the+/// authority; bound to `(request_id, reason, timestamp)` by a MAC.+#[derive(Clone, Copy, Debug)]+pub struct AuthorizationGrant {+ request_id: u64,+ timestamp: u64,+ reason_hash: u64,+ mac: u64,+}++/// How an un-marked output stays disclosed. Un-marking is not un-disclosing.+#[derive(Clone, Debug)]+pub enum ProvenanceDisclosure {+ /// A C2PA content-credential id attached to the output file's metadata.+ C2pa(String),+ /// An explicit AI-disclosure label surfaced to the reader.+ Label(String),+ /// An internal provenance-log record id.+ InternalLog(String),+}++impl ProvenanceDisclosure {+ fn describe(&self) -> Result<String, PolicyError> {+ let (kind, v) = match self {+ ProvenanceDisclosure::C2pa(v) => ("c2pa", v),+ ProvenanceDisclosure::Label(v) => ("label", v),+ ProvenanceDisclosure::InternalLog(v) => ("internal-log", v),+ };+ if v.trim().is_empty() {+ Err(PolicyError::EmptyDisclosure)+ } else {+ Ok(format!("{kind}:{v}"))+ }+ }+}++/// The outcome recorded for an un-marked generation attempt.+#[derive(Clone, Debug, PartialEq, Eq)]+pub enum AuditOutcome {+ /// Completed with a declared disclosure channel β compliant.+ Completed { disclosure: String },+ /// The session ended WITHOUT declaring disclosure β a compliance gap.+ AbandonedUndisclosed,+ /// Authorization failed; no generation occurred.+ Denied,+}++/// One immutable audit record. The durable evidence that an un-marked generation+/// happened, why, and whether it was disclosed.+#[derive(Clone, Debug)]+pub struct AuditRecord {+ pub request_id: u64,+ pub timestamp: u64,+ pub reason: String,+ pub outcome: AuditOutcome,+}++/// Where audit records go. A real deployment writes to an append-only store; the+/// in-memory sink is for tests / embedding.+pub trait AuditSink {+ fn record(&mut self, record: AuditRecord);+}++/// In-memory audit sink.+#[derive(Default)]+pub struct MemoryAuditSink {+ pub records: Vec<AuditRecord>,+}++impl AuditSink for MemoryAuditSink {+ fn record(&mut self, record: AuditRecord) {+ self.records.push(record);+ }+}++#[inline]+fn compute_mac(auth: AuthorizationKey, request_id: u64, reason_hash: u64, timestamp: u64) -> u64 {+ mix64(auth.0 ^ mix64(request_id) ^ mix64(reason_hash) ^ mix64(timestamp).rotate_left(17))+}++/// The governance policy. Holds the authority key and mints / verifies grants.+#[derive(Clone, Copy)]+pub struct UnmarkedGenerationPolicy {+ auth: AuthorizationKey,+}++impl UnmarkedGenerationPolicy {+ pub fn new(auth: AuthorizationKey) -> Self {+ UnmarkedGenerationPolicy { auth }+ }++ /// Authority action: mint a grant for one request. Unforgeable without the+ /// authority key. Binds the grant to this exact reason, request, and time.+ pub fn authorize(+ &self,+ request_id: u64,+ reason: &ExemptionReason,+ timestamp: u64,+ ) -> AuthorizationGrant {+ let reason_hash = reason.hash();+ AuthorizationGrant {+ request_id,+ timestamp,+ reason_hash,+ mac: compute_mac(self.auth, request_id, reason_hash, timestamp),+ }+ }++ /// Begin an un-marked session iff `grant` verifies for this `(request_id,+ /// reason, timestamp)`. On failure, a `Denied` audit record is written and+ /// no session is returned.+ pub fn begin<'s, S: AuditSink>(+ &self,+ grant: &AuthorizationGrant,+ request_id: u64,+ reason: &ExemptionReason,+ timestamp: u64,+ sink: &'s mut S,+ ) -> Result<UnmarkedSession<'s, S>, PolicyError> {+ let reason_hash = reason.hash();+ let expected = compute_mac(self.auth, request_id, reason_hash, timestamp);+ let ok = grant.mac == expected+ && grant.request_id == request_id+ && grant.reason_hash == reason_hash+ && grant.timestamp == timestamp;+ if !ok {+ sink.record(AuditRecord {+ request_id,+ timestamp,+ reason: reason.as_str().to_string(),+ outcome: AuditOutcome::Denied,+ });+ return Err(PolicyError::Unauthorized);+ }+ Ok(UnmarkedSession {+ sink,+ request_id,+ timestamp,+ reason: reason.as_str().to_string(),+ // Un-marked sampling seed. NOTE: the watermark key is deliberately+ // absent β this is plain sampling, so the output carries no mark. A+ // production deployment supplies real entropy here; determinism keeps+ // the crate testable and is irrelevant to the un-marked property.+ seed: mix64(request_id ^ timestamp.rotate_left(31)),+ draw: 0,+ done: false,+ })+ }+}++/// An authorized, in-progress un-marked generation. Produces un-marked tokens via+/// plain sampling (no watermark key). Must be completed with [`Self::finish`]+/// (declaring disclosure) or its drop commits an `AbandonedUndisclosed` record.+pub struct UnmarkedSession<'s, S: AuditSink> {+ sink: &'s mut S,+ request_id: u64,+ timestamp: u64,+ reason: String,+ seed: u64,+ draw: u32,+ done: bool,+}++impl<'s, S: AuditSink> UnmarkedSession<'s, S> {+ /// Emit one un-marked token: a plain categorical draw from `probs`, with the+ /// watermark key uninvolved. Returns an index into `probs`.+ pub fn step(&mut self, probs: &[f32]) -> usize {+ let idx = sample_index(probs, self.seed, self.draw);+ self.draw = self.draw.wrapping_add(1);+ idx+ }++ /// Complete the session by declaring how the output stays disclosed. Commits+ /// a `Completed` audit record. Consuming the session is what makes disclosure+ /// mandatory: you cannot cleanly finish without it.+ pub fn finish(mut self, disclosure: ProvenanceDisclosure) -> Result<AuditRecord, PolicyError> {+ let described = disclosure.describe()?;+ let rec = AuditRecord {+ request_id: self.request_id,+ timestamp: self.timestamp,+ reason: self.reason.clone(),+ outcome: AuditOutcome::Completed { disclosure: described },+ };+ self.sink.record(rec.clone());+ self.done = true;+ Ok(rec)+ }+}++impl<'s, S: AuditSink> Drop for UnmarkedSession<'s, S> {+ fn drop(&mut self) {+ if !self.done {+ // Ended without declaring disclosure β record the compliance gap.+ self.sink.record(AuditRecord {+ request_id: self.request_id,+ timestamp: self.timestamp,+ reason: self.reason.clone(),+ outcome: AuditOutcome::AbandonedUndisclosed,+ });+ }+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::context::WatermarkConfig;+ use crate::detect::detect_gumbel;+ use crate::hash::WatermarkKey;++ fn setup() -> (UnmarkedGenerationPolicy, ExemptionReason) {+ let policy = UnmarkedGenerationPolicy::new(AuthorizationKey::from_bytes(b"compliance-key"));+ let reason = ExemptionReason::new("internal eval corpus, not customer-facing").unwrap();+ (policy, reason)+ }++ #[test]+ fn empty_reason_rejected() {+ assert_eq!(ExemptionReason::new(" ").unwrap_err(), PolicyError::EmptyReason);+ }++ #[test]+ fn output_is_genuinely_unmarked() {+ // The point: an authorized un-marked session's output carries NO+ // watermark under the watermark key (plain sampling never used it).+ let (policy, reason) = setup();+ let mut sink = MemoryAuditSink::default();+ let grant = policy.authorize(42, &reason, 1000);+ let vocab = 128usize;+ let probs = vec![1.0f32 / vocab as f32; vocab];+ let mut session = policy.begin(&grant, 42, &reason, 1000, &mut sink).unwrap();+ let out: Vec<u32> = (0..600).map(|_| session.step(&probs) as u32).collect();+ session.finish(ProvenanceDisclosure::C2pa("cred-abc123".into())).unwrap();++ // Score it under a watermark key β must NOT be flagged (it's un-marked).+ let cfg = WatermarkConfig::new(WatermarkKey::from_bytes(b"any-key")).with_layers(1);+ let r = detect_gumbel(&out, cfg);+ assert!(!r.is_watermarked(1e-3), "un-marked output was flagged as watermarked: z={}", r.z_score);+ // And the audit shows a compliant, disclosed completion.+ assert_eq!(sink.records.len(), 1);+ match &sink.records[0].outcome {+ AuditOutcome::Completed { disclosure } => assert!(disclosure.starts_with("c2pa:")),+ o => panic!("expected Completed, got {o:?}"),+ }+ }++ #[test]+ fn forged_grant_is_denied_and_audited() {+ let (policy, reason) = setup();+ let mut sink = MemoryAuditSink::default();+ // A grant minted under a DIFFERENT authority key must not verify.+ let rogue = UnmarkedGenerationPolicy::new(AuthorizationKey::from_bytes(b"not-the-authority"));+ let forged = rogue.authorize(7, &reason, 500);+ let err = policy.begin(&forged, 7, &reason, 500, &mut sink).err().unwrap();+ assert_eq!(err, PolicyError::Unauthorized);+ assert_eq!(sink.records[0].outcome, AuditOutcome::Denied);+ }++ #[test]+ fn grant_bound_to_reason_and_request() {+ // A valid grant cannot be replayed for a different reason or request.+ let (policy, reason) = setup();+ let mut sink = MemoryAuditSink::default();+ let grant = policy.authorize(1, &reason, 100);+ let other_reason = ExemptionReason::new("a totally different justification").unwrap();+ assert!(policy.begin(&grant, 1, &other_reason, 100, &mut sink).is_err(), "reason not bound");+ assert!(policy.begin(&grant, 2, &reason, 100, &mut sink).is_err(), "request not bound");+ assert!(policy.begin(&grant, 1, &reason, 999, &mut sink).is_err(), "timestamp not bound");+ // The correct tuple works.+ assert!(policy.begin(&grant, 1, &reason, 100, &mut sink).is_ok());+ }++ #[test]+ fn abandoning_without_disclosure_is_recorded_loudly() {+ // Dropping a session without finish() must leave a compliance-gap record.+ let (policy, reason) = setup();+ let mut sink = MemoryAuditSink::default();+ let grant = policy.authorize(9, &reason, 200);+ {+ let mut session = policy.begin(&grant, 9, &reason, 200, &mut sink).unwrap();+ let _ = session.step(&[0.5f32, 0.5]);+ // no finish() β session dropped here+ }+ assert_eq!(sink.records.len(), 1);+ assert_eq!(sink.records[0].outcome, AuditOutcome::AbandonedUndisclosed);+ }++ #[test]+ fn empty_disclosure_rejected() {+ let (policy, reason) = setup();+ let mut sink = MemoryAuditSink::default();+ let grant = policy.authorize(3, &reason, 300);+ let session = policy.begin(&grant, 3, &reason, 300, &mut sink).unwrap();+ assert_eq!(+ session.finish(ProvenanceDisclosure::Label(" ".into())).unwrap_err(),+ PolicyError::EmptyDisclosure+ );+ // finish() failed, session consumed; drop path records the abandonment.+ assert_eq!(sink.records[0].outcome, AuditOutcome::AbandonedUndisclosed);+ }+}diff --git a/v3/crates/ruflo-watermark/src/wasm.rs b/v3/crates/ruflo-watermark/src/wasm.rsnew file mode 100644index 0000000000..05f3a5d1fb--- /dev/null+++ b/v3/crates/ruflo-watermark/src/wasm.rs@@ -0,0 +1,106 @@+//! WASM bindings (`--features wasm --target wasm32-unknown-unknown`).+//!+//! A thin, allocation-light surface over the core so JS/TS hosts (ruflo,+//! metaharness) can watermark a token stream and detect from a browser or Node+//! without a native addon. Token/probability slices marshal as typed arrays+//! (`Uint32Array` / `Float32Array`); detection results are a small struct with+//! getters.++use wasm_bindgen::prelude::*;++use crate::context::WatermarkConfig;+use crate::detect::{detect_gumbel, detect_tournament};+use crate::hash::WatermarkKey;+use crate::{Scheme, Watermarker};++fn cfg_from(material: &[u8], context_width: usize, layers: u32) -> WatermarkConfig {+ WatermarkConfig::new(WatermarkKey::from_bytes(material))+ .with_context_width(context_width)+ .with_layers(layers)+}++#[inline]+fn scheme_of(gumbel: bool) -> Scheme {+ if gumbel {+ Scheme::Gumbel+ } else {+ Scheme::Tournament+ }+}++/// Streaming watermarked sampler, JS-facing.+#[wasm_bindgen]+pub struct WasmWatermarker {+ inner: Watermarker,+}++#[wasm_bindgen]+impl WasmWatermarker {+ /// `key_material`: arbitrary secret bytes (e.g. a hex string's bytes).+ /// `gumbel`: `true` for the distortion-free scheme, `false` for tournament.+ #[wasm_bindgen(constructor)]+ pub fn new(key_material: &[u8], context_width: usize, layers: u32, gumbel: bool) -> WasmWatermarker {+ let cfg = cfg_from(key_material, context_width, layers);+ WasmWatermarker {+ inner: Watermarker::new(cfg, scheme_of(gumbel)),+ }+ }++ /// Emit one token: returns the index into `tokens`/`probs` of the chosen+ /// candidate. Advances the rolling context.+ pub fn step(&mut self, tokens: &[u32], probs: &[f32]) -> usize {+ self.inner.step(tokens, probs)+ }+}++/// Detection result, JS-facing (fields via getters).+#[wasm_bindgen]+pub struct WasmDetection {+ scored_positions: usize,+ z_score: f64,+ p_value: f64,+ log10_p: f64,+}++#[wasm_bindgen]+impl WasmDetection {+ #[wasm_bindgen(getter)]+ pub fn scored_positions(&self) -> usize {+ self.scored_positions+ }+ #[wasm_bindgen(getter)]+ pub fn z_score(&self) -> f64 {+ self.z_score+ }+ #[wasm_bindgen(getter)]+ pub fn p_value(&self) -> f64 {+ self.p_value+ }+ #[wasm_bindgen(getter)]+ pub fn log10_p(&self) -> f64 {+ self.log10_p+ }+}++/// Detect a watermark over an emitted token id sequence.+#[wasm_bindgen]+pub fn detect(+ tokens: &[u32],+ key_material: &[u8],+ context_width: usize,+ layers: u32,+ gumbel: bool,+) -> WasmDetection {+ let cfg = cfg_from(key_material, context_width, layers);+ let r = if gumbel {+ detect_gumbel(tokens, cfg)+ } else {+ detect_tournament(tokens, cfg)+ };+ WasmDetection {+ scored_positions: r.scored_positions,+ z_score: r.z_score,+ p_value: r.p_value,+ log10_p: r.log10_p,+ }+}diff --git a/v3/crates/ruflo-watermark/tests/end_to_end.rs b/v3/crates/ruflo-watermark/tests/end_to_end.rsnew file mode 100644index 0000000000..34b88bf766--- /dev/null+++ b/v3/crates/ruflo-watermark/tests/end_to_end.rs@@ -0,0 +1,76 @@+//! Black-box integration tests over the public API only β the shape a real+//! host (ruflo/metaharness) consumes.++use ruflo_watermark::{+ detect_gumbel, detect_tournament, robustness, Scheme, WatermarkConfig, WatermarkKey,+ Watermarker,+};++fn flat_candidates(vocab: u32) -> (Vec<u32>, Vec<f32>) {+ ((0..vocab).collect(), vec![1.0f32 / vocab as f32; vocab as usize])+}++fn generate(scheme: Scheme, cfg: WatermarkConfig, n: usize, vocab: u32) -> Vec<u32> {+ let (tokens, probs) = flat_candidates(vocab);+ let mut wm = Watermarker::new(cfg, scheme);+ (0..n).map(|_| tokens[wm.step(&tokens, &probs)]).collect()+}++#[test]+fn short_text_is_weaker_than_long_text() {+ // Anthropic's caveat: detection confidence grows with length. Verify the+ // z-score for a long watermarked stream exceeds that of a short one.+ let cfg = WatermarkConfig::new(WatermarkKey::from_bytes(b"len-test")).with_layers(6);+ let short = generate(Scheme::Tournament, cfg, 40, 128);+ let long = generate(Scheme::Tournament, cfg, 1000, 128);+ let zs = detect_tournament(&short, cfg).z_score;+ let zl = detect_tournament(&long, cfg).z_score;+ assert!(zl > zs, "long text ({zl}) not stronger than short ({zs})");+}++#[test]+fn factual_low_entropy_text_carries_little_watermark() {+ // Where there is only one plausible next token (near-deterministic p), the+ // watermark has nothing to ride β mirroring the "Principia Mathematica" and+ // code examples. A near-one-hot distribution should yield a weak signal.+ let cfg = WatermarkConfig::new(WatermarkKey(5)).with_layers(6);+ let vocab = 128u32;+ let tokens: Vec<u32> = (0..vocab).collect();+ // 99.9% mass on token 0: almost no low-stakes choice at any position.+ let mut probs = vec![0.001f32 / (vocab as f32 - 1.0); vocab as usize];+ probs[0] = 0.999;+ let mut wm = Watermarker::new(cfg, Scheme::Tournament);+ let stream: Vec<u32> = (0..800).map(|_| tokens[wm.step(&tokens, &probs)]).collect();+ let r = detect_tournament(&stream, cfg);+ // Far weaker than the flat-distribution case (which clears z>6 in unit tests).+ assert!(r.z_score < 4.0, "low-entropy text unexpectedly strong: z={}", r.z_score);+}++#[test]+fn deletion_attack_degrades_but_is_measured() {+ // Deletion desynchronizes contexts β a harder attack. The harness must still+ // return a finite, lower detection result (measurement, not a crash).+ let cfg = WatermarkConfig::new(WatermarkKey(9)).with_layers(6);+ let vocab = 128u32;+ let stream = generate(Scheme::Gumbel, cfg, 1000, vocab);+ let clean = detect_gumbel(&stream, cfg).z_score;+ let attacked = robustness::attack_delete(&stream, 0.3, 0xBEEF);+ let after = detect_gumbel(&attacked, cfg).z_score;+ assert!(after.is_finite());+ assert!(after < clean, "deletion did not reduce detectability: {clean} -> {after}");+}++#[test]+fn all_schemes_detect_their_own_output() {+ use ruflo_watermark::detect_tournament_nd;+ for scheme in [Scheme::Tournament, Scheme::TournamentNd, Scheme::Gumbel] {+ let cfg = WatermarkConfig::new(WatermarkKey::from_bytes(b"own")).with_layers(6);+ let stream = generate(scheme, cfg, 600, 128);+ let r = match scheme {+ Scheme::Tournament => detect_tournament(&stream, cfg),+ Scheme::TournamentNd => detect_tournament_nd(&stream, cfg),+ Scheme::Gumbel => detect_gumbel(&stream, cfg),+ };+ assert!(r.is_watermarked(1e-6), "{scheme:?} failed to detect its own output: z={}", r.z_score);+ }+}diff --git a/v3/docs/adr/ADR-383-watermarking-synthid-rust-wasm.md b/v3/docs/adr/ADR-383-watermarking-synthid-rust-wasm.mdnew file mode 100644index 0000000000..41d0ad716e--- /dev/null+++ b/v3/docs/adr/ADR-383-watermarking-synthid-rust-wasm.md@@ -0,0 +1,249 @@+# ADR-383 β LLM Text Watermarking (SynthID-Text / distortion-free) as a Rust/WASM component++- **Status**: Proposed+- **Date**: 2026-08-15+- **Component**: `v3/crates/ruflo-watermark` (self-contained crate; Rust core + optional WASM)+- **Related**: ADR-150 (MetaHarness optional/removable augmentation β this crate follows the same drop-in, no-required-runtime-dep discipline), the redblue adversarial harness (the robustness evaluator here is its watermarking analogue)+- **Prompted by**: the EU AI Act transparency requirement (in force 2026-08-02) that AI providers *mark* AI-generated content, and Anthropic's own rollout of SynthID-Text-style watermarking. ruflo/metaharness need a fast, embeddable implementation both to *produce* compliant marks on any locally-generated text and to *measure* watermark robustness as part of harness evaluation.++## Context++Autoregressive models pick one token at a time. At most positions several+candidates are near-equally plausible ("the weather is cold and **overcast**"+vs "β¦and **grey**"), and which one is emitted is settled by a random draw.+Watermarking changes only the *source of that randomness*: instead of an+arbitrary RNG, the draw is seeded by a secret key plus the preceding tokens.+The emitted text is still a valid model sample β no out-of-distribution words+are injected β but a holder of the key can later test whether a token sequence+rode the keyed stream and assign a probability that a keyed model produced it.+This is the "digits of pi instead of dice" analogy from Anthropic's explainer.++Three properties make this deployable and are the design targets here:++1. **No quality impact / no extra tokens.** The mark lives in tie-breaks among+ already-plausible candidates, so it does not change what the model can say,+ costs no extra tokens, and (for the distortion-free scheme) does not even+ change the marginal token distribution.+2. **Length-dependent, entropy-dependent detectability.** Confidence grows with+ the number of *low-stakes choices* the text contains. Factual or near-+ deterministic spans (Principia **Mathematica**; `2 + 2 = 4`; most code)+ carry little to no mark, by construction.+3. **Key-specific, carries no user information.** The key selects a+ pseudo-random stream; it encodes nothing about a user, org, or chat, and one+ provider's mark is invisible to another's detector.++### Scope decision (load-bearing): watermark + robustness evaluation, NOT a removal product++This ADR delivers watermark **generation**, **detection**, and a **robustness-+evaluation harness**. It deliberately does **not** deliver a general-purpose+watermark-*removal* / text-laundering tool.++The distinction is the same one drawn throughout the redblue work: implementing+attacks to *measure and harden* a defense is legitimate and valuable;+productizing an evasion tool is not. A watermark exists to satisfy an AI-content+transparency mandate and carries no user-identifying information, so a+turnkey stripper's only real-world effect is defeating provenance β passing AI+text off as un-marked, evading a legal transparency mechanism. The robustness+harness gives watermark *designers* everything they need (quantified detection+decay vs. attack strength) while operating on abstract token-id sequences and+returning *statistics*, not laundered natural-language text. See+`src/robustness.rs`'s module header for the enforced boundary.++## Decision++A single self-contained crate, `ruflo-watermark`, with two watermarking schemes+over shared infrastructure, a calibrated detector, a robustness harness, and an+optional WASM surface. The crate declares its own `[workspace]` so it builds and+tests standalone without perturbing ruflo's parent workspace (whose root+manifest documents why nested workspace roots stay isolated), and it is equally+droppable into `agent-harness-generator/crates/`.++### API boundary++The crate does **not** run an LLM. At each step the host supplies the model's+candidate token ids and their probabilities (typically a top-k slice); the+watermarker returns which candidate to emit. This is the correct deployment+shape (logits in β watermarked sample out) and keeps the crate model-agnostic,+tiny, and WASM-friendly.++### Shared infrastructure++- **Keyed PRF (`hash.rs`)** β the randomness source. A SplitMix64/MurmurHash3-+ family finalizer maps `(key, context, token_id, layer)` to a uniform `f64` or+ a fair coin bit. No tables, a few multiplies/xors, statistically uniform+ (`E[g] = 0.5` on unwatermarked streams β the null the detector tests against).+ **g-values are keyed on the token *id*, never a candidate list index**, so the+ detector β which sees only emitted token ids β reproduces the exact stream.+- **Context + masking (`context.rs`)** β each draw is seeded by the preceding+ `H` tokens (default `H=4`). Repeated-context masking skips watermarking (and+ detection) at any position whose `H`-gram context already occurred, which+ preserves the distribution on repetitive text and blunts "repeat the prompt"+ attacks. Generator and detector run the identical tracker, so scored positions+ match watermarked positions exactly.++### Scheme A β SynthID-Text Tournament (`tournament.rs`)++Draw `2^d` i.i.d. candidates from `p`, run a `d`-round single-elimination bracket+keeping the higher `g_β` each round, emit the winner. Strong; mildly+distortionary; strength and cost scale with depth `d`. The winner's g-values are+systematically high (`E β 2/3` per won layer), which detection exploits.++### Scheme B β distortion-free Gumbel / exponential-min (`gumbel.rs`)++For each candidate `i`, draw `u_i = g_unit(seed, id_i)`; emit `argmin_i+(-ln u_i)/p_i`. Provably samples exactly from `p` (marginal distribution+unchanged), while the emitted token's `u` is stochastically elevated. The right+choice when zero distortion is a hard requirement.++### Detection (`detect.rs`)++Re-runs the generator's context tracker, then aggregates per scheme: Tournament β+`Binomial(positionsΒ·d, Β½)` ones-count; Gumbel β `Gamma(positions, 1)` score-sum.+Both reduce to an upper-tail standard-normal p-value via a numerically-stable+`erfc` (accurate for large `z`, with an asymptotic `log10(p)` so extreme+confidences don't underflow to zero silently). `is_watermarked(alpha)` gives a+verdict at a chosen false-positive rate.++### Robustness harness (`robustness.rs`)++Deterministic substitution / deletion / span-resample attacks + a+`sweep_substitution` that returns the detectability curve (residual z / p vs.+edit rate). Measurement only; see the scope decision above.++### WASM (`wasm.rs`, `--features wasm`)++`wasm-bindgen` surface: a streaming `WasmWatermarker` and a `detect` function,+marshaling tokens/probs as typed arrays. 53 KB release artifact.++## Prior art++| Work | Scheme | Distortion | This crate |+|---|---|---|---|+| Aaronson (2022, unpublished talk) | exponential-min / Gumbel | distortion-free | Scheme B |+| Kirchenbauer et al. (2023), "A Watermark for LLMs" | green-list logit bias | distortionary | not implemented β biases the distribution more than the tie-break family; noted as an alternative |+| Kuditipudi et al. (2024), "Robust distortion-free watermarks" | exponential-min + edit-distance alignment | distortion-free | Scheme B is the sampler; alignment-based detection is future work (see Open Questions) |+| Dathathri et al. (2024, *Nature*), SynthID-Text | tournament sampling | tunable (distortionary / non-distortionary variants) | Scheme A |++SynthID-Text is the method Anthropic states it uses (a version of the Nature+approach, in the Aaronson lineage). We implement the practical distortionary+tournament plus the provably distortion-free Gumbel scheme so a host can pick+the distortion/strength trade-off explicitly.++## Optimization & measured performance++Mixer is branch-free and table-free; the hot path per emitted token is+`2^d` categorical draws + `d` coin-bit hashes (tournament) or one hash per+candidate (gumbel). Release profile: fat LTO, single codegen unit.++Measured (`cargo bench`, dev workstation, 256 candidates):++| Operation | Cost | Rate |+|---|---|---|+| Generation, tournament depth 2 (4 draws) | ~1.5 Β΅s/token | ~677 K tok/s |+| Generation, tournament depth 4 (16 draws) | ~3.7 Β΅s/token | ~273 K tok/s |+| Generation, tournament depth 8 (256 draws) | ~46 Β΅s/token | ~22 K tok/s |+| Generation, gumbel | ~2.0 Β΅s/token | ~494 K tok/s |+| Detection scan (either scheme) | β | ~10 M tok/s |++Generation at practical depths is single-digit microseconds per token β+negligible beside a model's millisecond-scale forward pass, matching the+"negligible impact on speed, no extra cost" claim. Detection scans at ~10M+tokens/sec, so a detection API is effectively free.++## Security & ethics++- **Key handling.** `WatermarkKey` carries no user information. Keys should be+ provisioned as secrets (GCP Secret Manager in this org); the crate never logs+ or serializes them.+- **No removal product.** Enforced by scope: the crate ships measurement, not a+ stripper (see Context).+- **Honest detection semantics.** A positive only means "a keyed model likely+ produced or heavily edited this"; it cannot distinguish authorship from heavy+ editing, says nothing about ownership, and (per the length/entropy properties)+ is weak on short or low-entropy text. `DetectionResult` exposes+ `scored_positions` so callers never over-read a verdict built on few choices.++## Evaluation++27 tests pass (22 unit + 4 integration + 1 doctest). Verified properties:+Gumbel distortion-freeness (marginals within 0.6% of `p`); PRF uniformity and+layer independence; wrong-key non-detection; length-scaling; low-entropy+weakness; repeated-context masking; monotonic robustness decay; and end-to-end+detection at `p < 1e-6` for both schemes with no false positive on null streams.+WASM target builds clean (53 KB).++## Consequences++- ruflo/metaharness gain a real, embeddable watermarking primitive usable from+ native Rust, Node/NAPI, or the browser (WASM) with no LLM dependency.+- The robustness harness slots into the harness-evaluation story: watermark+ strength becomes a measurable, defensible dimension like any other.+- Because the crate is self-contained and model-agnostic, adopting it is adding+ a member/vendoring a directory β not a framework commitment.++## Alternatives considered++- **Green-list logit biasing (Kirchenbauer)** β simpler but distortionary and+ operates on logits (needs the full vocab distribution, not a top-k slice);+ rejected as the default in favor of the tie-break family Anthropic actually+ uses, though it could be added behind the same `Scheme` enum.+- **Wrapping a C/C++ SynthID reference** β rejected: a dependency-free Rust core+ is smaller, WASM-native, and matches the org's "always Rust for these+ components" rule.++## Rollback++The crate is additive and isolated (own workspace, no parent-workspace member+entry required to exist). Rollback is deleting the directory; nothing else in+ruflo depends on it until a host explicitly wires it in.++## Indel robustness (addressed β `align.rs`, `evolve.rs`)++The initial framing ("degrades under deletion/insertion") was only partly right,+and measuring it corrected the diagnosis:++- **The context seed self-synchronizes.** Once an edit slides out of the+ `H`-token window, the observed window is again a run of consecutive generated+ tokens, so per-token scoring recovers automatically. In the flat/large-vocab+ regime the position-locked detector is therefore *already* indel-robust+ (measured: z ~unchanged self-sync vs locked up to 35% deletion).+- **The real gap is repeated-context masking desync**, which bites in the+ low-entropy / repetitive regime where real text with recurring phrases lives.+ There the position-locked detector is near-dead (measured zβ2.8) while the+ **self-synchronizing detector** (`detect_gumbel_selfsync`: score every position+ from its observed window, masking off, closed-form null) stays strong and+ indel-robust (measured zβ39β27 across 0β50% deletion). This is the fix.+- **Local-alignment detection** (`detect_gumbel_aligned`, a gap-tolerant+ max-segment scan, empirically null-calibrated) helps only for *concentrated*+ edits; it is the wrong statistic for the diffuse watermark signal and loses to+ plain self-sync in the repetitive regime (measured zβ0.5). It is retained,+ honestly scoped, and its parameters are what the bounded-evolution tuner+ (`evolve.rs`) searches β with the self-sync baseline reported as the reference,+ so "alignment did not beat self-sync here" is a first-class retained outcome,+ not a hidden regression.++## Third scheme + short-text detectors (implemented)++- **Non-distortionary tournament** (`Scheme::TournamentNd`, `tournament.rs`) β+ the balanced bracket with **continuous** g-values and mandatory repeated-+ context masking. Measuring it corrected an earlier mis-reading: the tournament+ is **non-distortionary in expectation over the key** β the key-averaged+ emitted distribution matches `p` to within sampling noise (measured drift+ < 0.3% at depths 1β5; test asserts < 0.6%). This is the SynthID-Text+ non-distortionary *config*; it is weaker than the *per-instance* distortion-+ freeness of `Scheme::Gumbel` (for a fixed key the tournament still biases+ toward high-g tokens β that bias is the watermark). Detects its own output at+ `p < 1e-6` with no null false-positive.+- **Short-text detectors** (`bayes.rs`) β (1) `detect_gumbel_exact` replaces the+ normal tail with the **exact** `Gamma(n,1)` upper tail (via Lanczos `ln_gamma`+ + regularized incomplete gamma), correct at small `n` where the normal approx+ misleads; (2) `detect_gumbel_hc` a **Higher-Criticism** statistic over per-+ token null tail probabilities, aimed at the sparse-signal (low-entropy) case.+ Both are calibrated (no null false-positive) and detect real watermarks.++## Open questions++1. **Insertion-specific alignment** β self-sync already recovers most insertion+ signal, but a phase-tracking detector could recover the straddle zone.+2. **HC power vs the sum** is asserted only as "calibrated + detects" here; a+ controlled power comparison across entropy regimes would quantify its edge.diff --git a/v3/docs/adr/ADR-384-generalized-bounded-evolution-methodology.md b/v3/docs/adr/ADR-384-generalized-bounded-evolution-methodology.mdnew file mode 100644index 0000000000..78e5f53fc1--- /dev/null+++ b/v3/docs/adr/ADR-384-generalized-bounded-evolution-methodology.md@@ -0,0 +1,377 @@+# ADR-384 β Generalized Bounded-Evolution Methodology (Darwin+Flywheel) with Error-Control Proof++**Status:** Proposed+**Date:** 2026-08-15+**Deciders:** ruflo-watermark maintainers, darwin-mode / agent-harness-generator maintainers, integration owner+**Supersedes/relates:** ADR-072/073/075 (Darwin cost/reproducibility/archive), ADR-099/101/102/106 (sandbox manifold + Tier2), ADR-112 (FDR small-n caveat), ADR-153/155 (bench suites, security harness), ADR-322 (flywheel receipts/promotion), ADR-381 (sequential-evidence e-process). In-crate instance: `crates/ruflo-watermark/src/{evolve.rs, align.rs}`.++---++## Context++Two systems in this monorepo implement the *same* bounded-evolution methodology with *zero shared code*:++1. **Darwin-mode harness-evolution** (`agent-harness-generator/packages/darwin-mode/src`, TypeScript): evolves a 7-file agent-harness genome (`planner/contextBuilder/reviewer/retryPolicy/toolPolicy/memoryPolicy/scorePolicy`), grades variants with a frozen 6-term scorer, promotes only through a 4-clause gate plus an optional statistical layer (bootstrap child-vs-parent, Benjamini-Hochberg FDR demote-only, monotonic SGM risk budget), and retains a whole-archive lineage.++2. **ruflo-watermark detector-tuning** (`crates/ruflo-watermark/src/{evolve.rs, align.rs}`, Rust): a `(1+Ξ»)` elitist strategy over a 3-field numeric genome (`AlignParams{band, gap_penalty, null_replays}`), a frozen `IndelBenchmark`, a frozen scalar fitness (`margin = mean_pos_z β max_neg_z`), one honest reference (`selfsync_reference`), full seeded determinism, retained lineage, and promotion deliberately left to the caller.++Both already assert the identical invariants β **frozen fitness declared before the run, bounded budget, retained lineage including failures, no auto-promotion, evaluation β promotion**. The generic *back half* of Darwin (selection zoo, BH-FDR / bootstrap / SGM statistics, whole-archive lineage) already operates on abstract `(variant, score, traces)`. The *front half* (genome, environment, fitness, reference, sandbox) is domain-welded in both. As a result the watermark crate cannot reuse a line of Darwin, and Darwin cannot express a numeric-parameter search.++We want one governed framework in which "evolve a 7-surface harness" and "tune a detector's parameters" are literal instances, and we want to state β honestly β exactly what error-control the framework buys and where the guarantees are only approximate.++**This ADR was written against a full adversarial statistical review and an implementation review.** Both are load-bearing. The central finding of the statistical review is uncomfortable and is stated up front rather than buried:++> **The shipped watermark crate does not currently possess the headline "bounded false-promotion" property.** Its only promotion guard is a single point comparison `best.margin > selfsync.margin` (`evolve.rs:143`) β no null, no variance, no error rate. The error-control machinery the proof relies on (ADR-381's e-process, or the meta-null permutation) is *not wired in*. The proof below certifies an **abstract tuner** and specifies what must be built; the crate as of this ADR is a partial instance. The implementation plan (Phase 0) is what makes the guarantee real for the watermark instance.++---++## Decision++Introduce a domain-agnostic bounded-search framework β **`ruflo-evolve`** (Rust) with a mirror **`@claude-flow/evolve`** (TypeScript) β whose contract is six abstractions plus a generic driver. Both flagship systems re-express themselves as thin adapters. The framework **coordinates and evaluates; it never promotes.** Promotion is a separate, signable, human-gated artifact.++The generic *back half* (selection strategies, statistics, lineage, driver) is shared as a specification realized twice (Rust value-typed + byte-deterministic; TypeScript async because the evaluator may be out-of-process/paid). The *front half* is injected per domain through traits.++### The six abstractions (Rust; TS mirror in Applicability)++```rust+pub type GenomeId = [u8;32];+pub type EvaluatorId = [u8;32];++// Deterministic PRNG addressed by (run_seed, generation, child).+// All SEARCH randomness flows through this (see revised invariant 5).+pub struct Prng(u64);+impl Prng { pub fn at(seed:u64, gen:u32, child:u32) -> Self; pub fn u01(&mut self)->f64; }++// (1) GENOME β unifies AlignParams(numeric) and the 7 policy surfaces(structured).+pub trait Genome: Clone + Send + Sync + 'static {+ fn seed() -> Self; // incumbent/default, deterministic+ fn mutate(&self, rng:&mut Prng) -> Self; // clamps into feasible region for numeric reps+ fn is_feasible(&self) -> bool; // load-bearing only when mutate cannot self-clamp (TS surfaces: compiles?)+ fn id(&self) -> GenomeId; // content hash β lineage id + dedup+}++// (2) METRIC β replaces the frozen 6-term scorer AND the scalar margin.+// Diagnostics live HERE (typed), NOT in a stringly-typed side channel (review finding 6).+pub trait Metric: Clone + Send + Sync + 'static {+ fn scalar(&self) -> f64; // total order for elitism / best()+ fn dominates(&self, o:&Self) -> bool; // Pareto β NO DEFAULT (review finding 9)+}++// Unified cost β the seam that makes iteration-count and paid spend one thing.+#[derive(Default,Clone)]+pub struct Cost { pub evals:u64, pub wall_s:f64, pub usd:f64, pub tokens:u64 }++// Immutable per-candidate evidence, retained whole; carries evaluator_id (frozen-env proof).+pub struct Receipt<G:Genome, M:Metric> {+ pub genome:G, pub genome_id:GenomeId, pub metric:M,+ pub evaluator_id:EvaluatorId, pub cost:Cost, pub coords:(u32,u32) /*gen,child*/,+}++// (3) FITNESS EVALUATOR (FROZEN) β replaces IndelBenchmark AND the three sandboxes.+pub trait FitnessEvaluator: Send + Sync {+ type G: Genome; type M: Metric;+ // Reserve β run β settle so a paid out-of-process judge is metered correctly+ // (review finding 2 β debit-before-work strands partial evals).+ fn reserve(&self, g:&Self::G, b:&mut Budget) -> Result<Ticket, Exhausted>;+ fn settle(&self, t:Ticket, g:&Self::G) -> Receipt<Self::G, Self::M>; // &self: never sees a verdict+ fn fingerprint(&self) -> EvaluatorId; // declared-before-run proof+ fn references(&self, b:&mut Budget) -> Vec<Receipt<Self::G,Self::M>>; // a LADDER, not one ref+}++// (4) LINEAGE STORE β generalizes the Archive; failures included, never dropped.+pub trait LineageStore { type G:Genome; type M:Metric;+ fn record(&mut self, r:Receipt<Self::G,Self::M>); // called BEFORE any comparison+ fn all(&self) -> &[Receipt<Self::G,Self::M>];+ fn best(&self) -> Option<&Receipt<Self::G,Self::M>>;+}++// (5) PROMOTION GATE β first-class, signable, SEPARATE from search.+pub enum Verdict { Promote, Retain(String) }++// Null evidence is NOT replay-shaped by contract (review finding 5): the metaharness+// instance clears winner's-curse with bootstrap/FDR, which has no null_mean/null_sd.+pub enum NullEvidence {+ Replayed(Standardized), // watermark: wrong-key / meta-null z+ Bootstrap { q:f64, method:&'static str },// metaharness: BH-FDR / bootstrap+ Absent { reason:&'static str }, // must be justified; a Promote with Absent is a policy error+}++pub struct PromotionReceipt {+ pub genome_id:GenomeId, pub evaluator_id:EvaluatorId, pub gate_seed:u64, pub verdict:Verdict,+ pub evidence: serde_json::Value, // margins-vs-refs, null evidence, FDR q, SAFETY-FLOOR result+ pub signature: Option<[u8;64]>, // Ed25519; ONLY on a policy-authorized promote+}+pub trait PromotionGate { type G:Genome; type M:Metric;+ // PURE. Never mutates a running incumbent. MUST evaluate a declared safety floor+ // (review finding M) in addition to beats-references + null-cleared + statistical checks.+ fn safety_floor(&self, cand:&Receipt<Self::G,Self::M>) -> Result<(), String>;+ fn admit(&self, cand:&Receipt<Self::G,Self::M>,+ refs:&[Receipt<Self::G,Self::M>],+ null:&NullEvidence, stats:&serde_json::Value) -> PromotionReceipt;+}+```++### (6) The lifted primitive β EmpiricalNullCalibrator + NuisancePreservingNull++The watermark's wrong-key replay and the missing winner's-curse guard are one contract: *recompute the selection statistic under a signal-destroying, nuisance-preserving perturbation, then standardize.* Factor it out of `detect_gumbel_aligned` so both levels reuse it, and make it accept a **pluggable null estimator** (replay OR bootstrap/analytic surrogate β review finding 8):++```rust+pub trait NuisancePreservingNull { type Ctx;+ fn perturb(&self, base:&Self::Ctx, replica:u32) -> Self::Ctx; } // identical nuisance, zero signal++pub struct Standardized { pub observed:f64, pub null_mean:f64, pub null_sd:f64, pub z:f64, pub p_perm:f64 }++pub struct EmpiricalNullCalibrator;+impl EmpiricalNullCalibrator {+ pub fn calibrate<C>(&self, base:&C, observed:f64,+ stat: impl Fn(&C)->f64, null:&impl NuisancePreservingNull<Ctx=C>, replays:u32) -> Standardized;+}+```++### Driver (the generic back half β structurally cannot promote)++```rust+pub struct EvolutionOutcome<G:Genome,M:Metric> {+ pub best:Receipt<G,M>, pub references:Vec<Receipt<G,M>>,+ pub lineage:Vec<Receipt<G,M>>, pub meta_null:NullEvidence,+}+pub fn evolve<E,S>(ev:&E, store:&mut dyn LineageStore<G=E::G,M=E::M>,+ strat:&S, budget:Budget) -> EvolutionOutcome<E::G,E::M>+where E:FitnessEvaluator, S:SelectionStrategy<G=E::G,M=E::M>;+// seed β reserve/settle β record; per gen: strat.parents(store.all());+// child = parent.mutate(Prng::at(seed,gen,child)); skip if !feasible;+// reserve/settle or halt on Exhausted; record EVERY child incl. losers;+// stop on budget.exhausted(); compute references + meta_null. NEVER calls a PromotionGate.+```++`Budget` is the single place iteration-count and spend unify β a monotonic, non-refillable ledger with `reserve β settle` two-phase accounting.++---++## Formal Properties & Proof++We formalize the abstract tuner `(Ξ, D, E, f, b, Search, Gate)` and prove three properties. **Every assumption is stated; every approximation is flagged.** The running instance is the watermark crate; the guarantees hold for the *abstract tuner once Phase 0 is built*, not for the crate as shipped today.++The abstract object: Ξ genome space; `E=(P positives, N negatives)` a benchmark drawn **once** from D and **frozen** before any candidate exists; `f:Ξββ` a **pure** function of `(ΞΈ,E)` a candidate cannot alter; reference `b` scored on the same E; `Ξ(ΞΈ)=f(ΞΈ)βf(b)` a **paired** contrast; Search bounded and seed-deterministic β `mutate` reads only `(seed,gen,child)`, never a fitness value; winner `ΞΈ* = argmax_k f(ΞΈ_k)`, stream length `M=1+GΒ·C`; Gate separate from search.++### Claim 1 β frozen fitness + held-out benchmark bounds over-optimism of the *pos_mean* term of the selected candidate++**Assumptions.** (A1) E frozen, independent of the mutation operator; (A2) `f` pure in `(ΞΈ,E)` β no self-grading; (A3) per-positive-stream contributions concentrate (see flag G below).++**Key move (load-bearing, and its limits).** Because `mutate` deltas depend on the **seed, not on fitness**, the set of *reachable* candidates is finite and **E-independent**, fully determined by `budget.seed`: `|R_reach| = O(C^G)`, `log N_reach β 8` at G=4,C=6. Seeded determinism is therefore *part of the proof*, not just reproducibility hygiene. A union bound over the E-independent `R_reach` gives, w.p. β₯ 1βΞ΄:++`F_pos(ΞΈ*) β₯ f_pos(ΞΈ*;E) β ΟΒ·β(2 log(N_reach/Ξ΄)/|P|)`.++Elitism additionally gives `f(ΞΈ*) β₯ f(baseline)` deterministically (no in-sample regression).++**Flags / approximations (adversarial points EβH, K, F, G).**++- **[FLAG β scope; adversarial F].** This bound covers **only the `pos_mean` term** (a mean of iid streams). It does **not** cover `neg_max_z`, the safety-critical FP term: `neg_max_z(ΞΈ*) = max over the negative *set*` at an adaptively-selected ΞΈ*, which is itself a selection statistic. **Neither Claim 1 (a mean bound) nor Claim 2 (a per-stream null) bounds `E[neg_max_z(ΞΈ*)] β true`.** The one quantity the safety gate (`neg_max_z < 4.0`) depends on has *no analytic over-optimism control*. This is closed operationally by the independent-gate split (Claim 3 / Phase 0): `neg_max_z` is re-measured on an independent seed B and the `< 4.0` clause is enforced on B, where selection did not act on it. We state plainly: **the analytic bound does not reach the safety term; only the split does, and the split gives an unbiased estimate, not a closed-form certificate.**++- **[FLAG β assumption conflict; adversarial G].** A3's Ο-sub-Gaussian assumption **contradicts** Claim 2's admission that the per-stream z's are a Gaussian standardization of a right-skewed extreme (heavier-than-Gaussian tails). We cannot have both. Resolution: replace A3 with a **bounded-support / empirical-Bernstein** concentration β post-calibration z is clamped to a finite range in practice, and we use `ΟΜ` estimated with its own inflation term. The bound then carries a variance-of-variance correction and is **weaker than the clean sub-Gaussian form.** We do not claim the sub-Gaussian constant.++- **[FLAG β numerically empty at deployed sizes; adversarial H/I].** At `|P|β20`, `Ξ΄=0.05`, `log N_reachβ8`: slack `β ΟΒ·β(22/20) β 1.05Ο` β comparable to the margins themselves (order 1); at `|P|=6` (the ADR-112 floor) it is `β1.9Ο`. **The analytic certificate is asymptotically sound and empirically vacuous at the sizes the system runs.** Therefore Claim 1 is *not* the operative guarantee. The operative guarantee is the empirical independent-gate split + the corrected meta-null permutation (Claims 3). Claim 1 is retained as a qualitative statement (over-optimism grows only `β(log N_reach) = O(β(G log C))` in search effort) and as motivation for keeping the seed E-independent β not as a numeric bound we rely on.++- **[FLAG β per-seed; adversarial K].** `R_reach` is per-seed. Running M seeds and reporting best-across-seeds is uncontrolled optional stopping that widens the bound to `log(MΒ·N_reach)`. **Mitigation (governed):** the run seed is pre-registered and persisted in the `PromotionReceipt.gate_seed`, exactly as the k-index is persisted for Claim 3; seed-shopping is a policy violation, not a free move. The meta-null (which *requires* B reruns with varied seeds) uses a fixed, declared seed schedule.++### Claim 2 β empirical-null (wrong-key replay) gives a valid null; the per-stream z/p is not (badly) anti-conservative++The statistic `T(ΞΈ;key)=local_align_max(centered_scores(tokens,key))` is a max-over-alignment-paths quantity whose naive null is right-skewed. Calibration recomputes `T` under `K=null_replays` wrong keys (nuisance-preserving: identical tokens/marginal law/band/gap; signal-destroying), then standardizes.++**Assumptions.** (i) under H0 the stream is independent of all K+1 keys (true for a genuine null stream); (ii) **hash idealization** β `mix64`/`context_seed` as a random oracle.++**Exact result.** Under (i)+(ii), `(T_obs, T_1,β¦,T_K)` are **exchangeable**, so the permutation p-value `p_perm = (1 + #{r: T_r β₯ T_obs})/(K+1)` satisfies `P_{H0}(p_perm β€ Ξ±) β€ Ξ±` **exactly** (finite-sample).++**Flags / approximations (adversarial E).**++- **[FLAG β as-coded β as-proved].** The code uses a Gaussian standardization + `normal_upper_tail(z)`, **not** `p_perm`. This corrects the first two moments (removes the dominant max-over-paths inflation) but leaves residual far-tail miscalibration from (a) finite K estimating (mean,sd) with Kβ1 dof and (b) Gaussianizing a skewed extreme β so `z` is mildly inflated deep in the tail. **Exact Ξ±-testing requires `K β₯ 1/Ξ± β 1`** (default K=24 floors at p=1/25). Phase 0 emits `p_perm` alongside `z` and the gate consumes `p_perm` (or a fitted Gumbel/GPD tail) for the promotion decision; the evolved `z` remains only a ranking signal.++- **[FLAG β frozen-kernel is overclaimed for this instance; adversarial E, review finding 1].** `null_replays` is an **evolvable genome field** consumed directly to compute `(mean_null, sd_null)`. "A variant cannot re-grade itself" is true only of the *formula*; the candidate selects the *calibration* fed into it, and `argmax margin` will preferentially pick genomes whose fixed-seed `(K, replay-seeds)` realization yields a lucky-low `sd_null`. **This is a live selection-of-calibration-noise channel Claim 2 does not bound, and it is a correctness bug in the shipped crate, not merely a design nicety.** Fix (Phase 0, mandatory): the promotion gate **re-scores the winner and every reference at a fixed, pre-registered `k*`** (e.g. 48) β nearly free because caching already holds all `r<48` wrong-key vectors. The frozen-kernel invariant is restated honestly as *frozen formula + frozen gate-time calibration*, and `null_replays` may vary during *search* but not at the *gate*.++### Claim 3 β family-wise false-promotion control under an adaptively-chosen candidate stream++Two routes. **Both require the independent-gate split** β this resolves the contradiction the two source documents left open (adversarial C): the efficiency lemma says the split is mandatory; the naive Claim-3 statement applied the e-process to the shared E. **We adopt the split as mandatory.** Select on seed A; gate on independent seed B β selection.++**Route A β sequential e-process (ADR-381), applied on B.** Per candidate k, an anytime-valid e-process bets `(1+Ξ»)` on candidate-wins / `(1βΞ»)` on baseline-wins over discordant McNemar pairs *drawn from seed B*. Under the **sign null** `H0^k: P(discordant pair favors candidate) β€ Β½`, `(E_k^t)` is a non-negative supermartingale with `E[E_k^0]=1` w.r.t. the filtration including all prior candidates' B-data. Ville's inequality β per-candidate type-I β€ Ξ±_k under *any* stopping rule. Basel allocation `Ξ±_k = Ξ±_totalΒ·6/(ΟΒ²kΒ²)` with `Σα_k = Ξ±_total` and an independence-free union bound β `P(β false promotion) β€ Ξ±_total`.++**Route B β meta-null permutation (the corrected nuisance-preserving form).** Re-run the *whole* bounded evolution B times against a nuisance-preserving, signal-free benchmark; `p_meta = (1+#{null-best β₯ real-best})/(B+1)` is an exact permutation test of the global "the gain is chance" null for the single selection, provided identical budget/seed discipline per rerun and provided the null is genuinely nuisance-preserving.++**Flags / approximations (adversarial B, C, D, I, J, L, N) β stated explicitly.**++- **[FLAG β wrong functional; adversarial B].** Route A controls the **sign/win-rate null**, which is **orthogonal to the safety-critical worst-case FP** encoded in `neg_max_z`. A candidate can win >Β½ of discordant pairs (legitimately clearing Route A) while being *worse* on one catastrophic negative. **The e-process alone is insufficient for a detector.** The `PromotionGate::safety_floor` predicate is therefore **not optional**: the watermark gate must enforce `neg_max_z(best on B) < 4.0` as a hard clause *in addition to* the FWER test. We do not claim the e-process bounds the worst-case FP; it does not.++- **[FLAG β martingale breaks under benchmark reuse; adversarial C β RESOLVED by making the split mandatory].** Applying the e-process to the *same* E used for selection violates the conditional-Β½ assumption (testing on the training set). This ADR **removes that unsoundness by requiring seed B β selection.** Any implementation that scores the e-process on the selection benchmark is out of contract.++- **[FLAG β Ξ±-allocation is power-adverse; adversarial D].** Basel `Ξ±_kβ1/kΒ²` gives the *least* budget to *late* candidates β which, in an evolutionary loop, are the *most likely genuine wins*. Validity survives; **usable power collapses for exactly the improvements we want.** The "fix" of reusing/resetting k is the Ξ±-double-spend the proof forbids. Consequence we accept: for the watermark's single-selection question, **prefer Route B** (the meta-null permutation), which spends Ξ± once on the whole selection and is not subject to the position-dependent starvation. Route A is retained for metaharness's genuinely sequential candidate stream where per-candidate control is the right shape; its power limitation is documented, not denied.++- **[FLAG β meta-null is NOT nuisance-preserving as originally specified; adversarial I β this is the deepest correction].** A "positive built without the watermark key" is an **unwatermarked-then-attacked** stream, whose token marginal differs from a **watermarked-then-attacked** stream β because watermarking *is* a shift of the sampling distribution. So the naive signal-free benchmark draws from a different token law, and `p_meta` becomes an exact test of the *wrong* null (potentially anti-conservative). **Correction adopted here:** build the meta-null by **holding the real watermarked-then-attacked positives fixed and replacing the detector's key with wrong keys at the meta level** β i.e., run the entire evolution scoring against *wrong-key readings of the genuine positive streams*. This preserves the token law exactly (the streams are still watermarked+attacked) while destroying the detector's access to signal β the wrong-key-replay principle lifted correctly to the meta level. This is the watermark-domain-valid meta-null; the "unwatermarked positives" construction is rejected. **Even so, `p_meta` remains conditional on the hash idealization (ii) and on B being finite (quantile uncertainty ~1/B); we report B and use a conservative high quantile.**++- **[FLAG β self-calibration fails under a signal-adaptive proposer; adversarial J].** The meta-null "self-calibrates to whatever selection intensity the optimizations create" **only for a signal-independent proposer** (blind seeded mutation). A surrogate (EI over lineage) fits a real gradient on the real benchmark and pure noise on the null β its induced selection intensity differs, so the null under-reproduces the real funnel. **Consequence:** the calibrated guarantee is claimed **only when the proposer is signal-independent** (Phase 0/1). The surrogate (Phase 3) ships behind the split, and its meta-null is generated with the *same surrogate and same seed schedule* as a best-effort match, with the residual mismatch flagged as an **open question**, not a proven guarantee.++- **[FLAG β generalization dissolves f-purity; adversarial L].** Claims 1β3 assume `f(ΞΈ;E)` is a **pure, deterministic** real number (Claim 2's exchangeability treats the K+1 T-values as deterministic given the stream; Claim 1 union-bounds over a finite genome set). A metaharness **paid out-of-process judge is stochastic per call.** Then `R_reach` is no longer the covering object, `fingerprint()` proves *nothing* about grading stability (a stable fingerprint with varying grading is possible), and permutation exactness is gone. **We therefore state which guarantees hold where:** the exact permutation/finite-sample results hold **only for the watermark's pure in-process f**; for metaharness, invariant 5 relaxes to "seeded + variance-bounded", Claim 2's exactness degrades to a **bootstrap/variance-bounded approximation**, and Claim 3 uses BH-FDR/bootstrap (`NullEvidence::Bootstrap`) rather than replay. The "one framework, two instances" thesis holds at the level of *the specification and the gate interface*; it does **not** claim the watermark's exact statistics transfer unchanged to a stochastic judge.++- **[FLAG β safety-of-selection, not safety-of-detection; adversarial N].** Every bound is conditional on `E ~ D`. A deployment attacker is adaptive and free to attack outside E's support. **"Bounded false promotion" means "bounded probability of promoting a detector that fails to beat baseline *on E*" β a selection guarantee, not a deployment guarantee.** Under an adaptive attacker the entire edifice is vacuous regardless of statistical tightness. Mitigation (adversarial-benchmark refresh) is real work but **out of scope for the error-control proof** and is listed under Open Questions.++**Integration.** Claim 1 (qualitatively) bounds over-optimism of the pos_mean term and motivates seed-determinism, but is numerically empty at deployed |P|. Claim 2 makes each per-stream statistic a validly-calibrated null (exact via `p_perm`; approximate as-coded via `z`). Claim 3 β on the *independent gate seed B*, with a mandatory `neg_max` safety floor, via the corrected wrong-key meta-null (watermark) or bootstrap/FDR (metaharness) β converts "best on frozen E" into a governed promotion whose family-wise false-promotion probability β€ Ξ±_total *for the selection question on E*. The crate acquires this property only after Phase 0.++---++## Optimization++Every optimization touches only the **proposer** (what to try), the **scheduler** (order/parallelism), or a **memoization** of the pure evaluator β **never the grader**. Two safety classes:++- **EXACT** β value-identical to sequential by referential transparency or an unbiased-difference estimator. Cannot bias the comparison or inflate FP.+- **SELECTION-ONLY** β may only prune/reorder; an error costs optimality, never correctness, **provided the final gate runs at full fidelity on the independent split B.**++The five techniques and their proofs-of-no-bias:++1. **Successive halving / early stopping β SELECTION-ONLY.** Cheap rung β richer rung. Reported margins of survivors + references are full-fidelity. **Two hard constraints:** (a) **subsample positives only, never negatives** β `margin` uses `neg_max`, and max-over-subset β€ max-over-full biases margin *upward for exactly the FP-risky candidates the safety clause exists to catch*; (b) rung item-subsets are seed-determined a priori, never chosen from observed scores.+2. **Empirical-null variance reduction.** (2a) **CRN β EXACT, already latent:** the wrong-key seed `mix64(cfg.key.0 ^ (0xA5A5_0000 ^ r))` is candidate-independent and prefix-stable in `r`, so all candidates share null draws β cross-candidate margin differences are low-variance. (2b) **Control variate β EXACT iff Ξ² pre-registered:** use the closed-form self-sync sum (analytic null mean) as a proxy; in-sample Ξ² injects O(1/k) bias, so Ξ² is frozen before the run. (2c) **Adaptive replays β SELECTION-ONLY in pruning only:** data-dependent K at the *gate* is optional stopping; the gate re-scores at the fixed pre-registered `k*` (finding 1 / Claim 2 fix), neutralizing both the optional-stopping channel and the calibration-noise-selection channel.+3. **Surrogate-assisted proposal β PROPOSER-ONLY.** Fewer full evals to a given margin. **The real hazard:** denser search = stronger winner's curse + noise-exploitation. Neutralized **only** by the mandatory independent-gate split + a meta-null generated through the *same* surrogate pipeline. Without the split the surrogate *will* inflate false promotion. (Residual mismatch under a signal-adaptive proposer: see Claim 3 flag J β open.)+4. **Parallel-across-candidates with deterministic seeds β EXACT.** `fitness` reads only immutable bench data + params + pure seed derivations; parallelize across candidates, index lineage by `(gen,child)`, keep **intra-candidate folds fixed-order** (a nondeterministic parallel float sum breaks byte-repro β a stated safety property).+5. **Per-item caching of `centered_scores` β EXACT, highest-value.** `centered_scores(tokens,key,h)` is `AlignParams`-independent; cache per `(item, key-role β {real, wrong_r})` once. Per-candidate cost collapses to the O(nΒ·band) DP; the O(nΒ·H) hashing is paid once for the whole run. Prefix-stable seeds mean one `r<48` cache serves every `null_replays` value and delivers CRN (2a) for free. Cache key must include every value-affecting input, guarded by an equality assertion against a freshly recomputed reference on a sampled item.++**Increment order (the framework is NOT a prerequisite for the speedups β review finding 3):**+`{5, 4, 2a, 2b}` (EXACT, in-crate, byte-safe) β `{fixed-k* gate + independent-gate split + corrected meta-null}` (semantic; Phase 0) β `{1, 2c-pruning, 3}` (SELECTION accelerators, only after the split exists).++The RΓ meta-null cost is affordable for the pure in-crate watermark precisely because 4+5 make each run cheap (note: the per-item cache does **not** transfer across the B meta-null benchmarks, since each null run reads different key-roles β caching helps *within* a run). For the paid metaharness judge, RΓ full evolutions is prohibitive, so the calibrator there uses a bootstrap/analytic surrogate, not replay β same *interface slot* (`NullEvidence`), different calibrator per cost regime.++---++## Applicability++The two flagship systems are literal instances of the same six abstractions.++**ruflo-watermark (pure, in-process, deterministic β the exact-guarantee instance):**+- `Genome = AlignParams` (`mutate` = existing clamped perturbations `evolve.rs:153-162`; `is_feasible` dead-but-true because numeric `mutate` self-clamps).+- `Metric = ScalarMargin{margin, pos_mean_z, neg_max_z}` (typed diagnostics live in `M`, no JSON side channel); `scalar()=margin`; `dominates` = scalar (single-objective).+- `FitnessEvaluator = IndelBenchmark`, `Cost{evals:1}`, `fingerprint = hash(cfg,vocab,seed,streams)`, `references = [default-params baseline, self-sync]`.+- `PromotionGate = MarginGate`: `safety_floor` = `neg_max_z < 4.0` (hard); `admit` Promote iff margin > every reference on **seed B** AND `NullEvidence::Replayed` (meta-null) clears threshold AND no-regression re-checked on B.+- Calibrator level-1 = wrong-key replay (extracted from `align.rs:139-150`); level-2 = **corrected wrong-key meta-null over the genuine positives** (closes the winner's-curse gap; nuisance-preserving by construction).++**metaharness harness-evolution (out-of-process, paid, stochastic β the approximate-guarantee instance):**+- `Genome = SevenSurfaces` (`mutate` = regex perturb; `is_feasible` = importable/compiles / Tier2 `--experimental-strip-types` check β here `is_feasible` is load-bearing because `mutate` cannot self-clamp).+- `Metric = Graded{tpr, fpr, patch_pass, cost}` with a **real** `dominates` (Pareto β no default) + a declared scalarization for elitism.+- `FitnessEvaluator` = test command / paid model judge β `Cost{wall_s, usd, tokens}` (this is why `reserve/settle` and the spend budget exist); `references = [B0 static, B1 LLM-single, B2 fixed-agent, B3 prior champion]`.+- `PromotionGate = FlywheelGate`: `safety_floor` = FPR/unsafe clauses; `admit` = BH-FDR (demote-only) + bootstrap child-vs-parent + SGM monotonic risk budget + Ed25519 signed-promote; `NullEvidence::Bootstrap`.+- Calibrator = bootstrap/FDR over the β₯5-task corpus (the existing empirical-null audit dashboard), not replay.++The anti-substitution rule (`evolve.rs:2-9` β refusing to shell to metaharness-darwin because it would "evolve the wrong thing") is *satisfied*: the shared artifact is the **methodology (traits)**, not a shared evaluator. Neither crate pulls the other's domain code.++**Honest scope of "one framework" (review finding 4):** it is **one specification, two implementations** sharing no compiled artifact (Rust crate + separate TS package). Of the six invariants, **byte-determinism (5) and fingerprint-frozen-fitness (2) are structurally enforced only in Rust**; in TypeScript they degrade to convention (interfaces cannot enforce record-before-compare, Prng-only randomness, or verdict-blindness), and for a stochastic paid judge determinism relaxes to "seeded + variance-bounded". The framework's value is **contingent on both adopters implementing the traits** β if darwin-mode keeps its bespoke TS loop, `ruflo-evolve` is indirection for a single caller. This is why the framework extraction (Phase 2) is gated on a darwin-mode commitment, and the exact speedups + Phase-0 correctness fixes land first, independent of any abstraction.++---++## Security / Governance++- **Evaluation β promotion, structurally.** `evolve()` returns an `EvolutionOutcome` and *cannot* mutate an incumbent. Only a separate `PromotionGate::admit()` produces a `PromotionReceipt`. Wiring the winner in is a human decision.+- **No auto-promotion.** No code path signs a `PromotionReceipt` without a policy-authorized promote step; a `Verdict::Promote` carrying `NullEvidence::Absent` is a policy error and is rejected.+- **Human gate.** Signing is Ed25519 with a policy-held key (the flywheel signed-promote model, ADR-322). Darwin, Flywheel, MetaHarness, and this framework may propose and evaluate; they cannot self-promote or widen tools/network/secrets/spend/concurrency.+- **Frozen evaluator, verdict-blind.** `evaluate` takes `&self`; `fingerprint()` stamps every receipt; the driver asserts all receipts in a run share one `evaluator_id`. The evaluator never receives a verdict β a candidate cannot re-grade itself. **Caveat (adversarial L):** `fingerprint()` catches accidental drift, **not** a stable-fingerprint stochastic judge; for paid judges this is a "seeded + variance-bounded" posture, not a cryptographic freeze.+- **Mandatory safety floor.** `PromotionGate` must implement `safety_floor` (review finding M): the FP-critical axis is checked *outside* the scalar score, because elitism's no-regression is on `Metric::scalar()` and a Pareto metric can improve the scalar while regressing FPR. The floor is re-checked on the independent seed B.+- **Governed seeds.** Run seed and gate seed B are persisted in the receipt; seed-shopping across runs is a policy violation (adversarial K).+- **Bounded resource use.** Non-refillable `Budget` ledger; the driver halts on `exhausted()` or the first `Exhausted` from `reserve`.++---++## Evaluation plan++Each phase ships behind **tests + a frozen benchmark** (byte-reproducible fixture; no wall-clock in any graded quantity).++1. **Exact-speedup equivalence.** Golden-master test: `{5,4,2a,2b}` produce **byte-identical** `margin`/`neg_max_z`/promoted-verdict to the current sequential loop on a frozen `IndelBenchmark` seed. Fail on any float divergence.+2. **Calibration validity (Claim 2).** Feed genuine null streams; assert `p_perm` controls type-I at Ξ± (`P(p_perm β€ Ξ±) β€ Ξ±` over β₯10k trials); assert the as-coded `z`-path is *not worse than* `p_perm` in the body and record its far-tail anti-conservatism as a measured caveat.+3. **Winner's-curse control (Claim 3, Route B).** On a signal-free (**wrong-key-over-genuine-positives**) meta-benchmark, measure empirical false-promotion rate of the full pipeline (incl. halving) at `p_meta β€ Ξ±`; require β€ Ξ± + quantile slack; report B.+4. **Split necessity (adversarial C).** Ablation: run the gate on the selection benchmark vs seed B; demonstrate the shared-E gate inflates false promotion and the split restores control.+5. **Safety-floor orthogonality (adversarial B/F).** Construct a candidate that wins >Β½ discordant pairs but regresses `neg_max_z`; assert the FWER test *passes* and the `safety_floor` *rejects* β proving the floor is load-bearing.+6. **FDR small-n (ADR-112).** Below 5 tasks, assert the gate falls back to conservative non-promotion, not a mis-calibrated pass.+7. **Metaharness parity.** The darwin adapter reproduces the existing ADR-099 empirical-FDR audit (FDRβ0.049 at q=0.05 on true-null uniform p-values) through the new `PromotionGate`/`NullEvidence::Bootstrap` path.+8. **Adopter drill.** `ruflo-watermark` and `darwin-mode` both compile against the traits; a CI job asserts the watermark crate's bespoke loop is deleted and re-expressed as an adapter.++---++## Consequences++**Positive.** One governed methodology; the watermark crate acquires real winner's-curse control it lacks today; the `neg_max` safety term gets an explicit floor; the exact speedups make the RΓ meta-null affordable; the frozen-kernel claim is made honest (fixed-k* gate); Darwin and the watermark tuner share statistics without sharing domain code.++**Negative / accepted.** The analytic Claim 1 is numerically empty at deployed |P| and is demoted to motivation, not certificate. The FWER guarantee is over the sign null, not the worst-case FP β the floor, not the e-process, protects safety. Basel Ξ±-allocation is power-adverse for late (best) candidates, pushing the watermark toward Route B. The meta-null is exact only under the hash idealization and the corrected wrong-key construction; under a signal-adaptive surrogate self-calibration is best-effort, not proven. The "one framework" is one spec / two implementations; structural enforcement is Rust-only; value is contingent on darwin-mode adopting the traits. All guarantees are safety-of-selection-on-E, **not** safety-of-detection under an adaptive attacker.++---++## Alternatives++1. **Do nothing / copy-paste.** Keep two welded implementations. Rejected: no shared statistics, and the watermark crate keeps its zero-meta-level-control and its calibration-noise bug.+2. **Shell the watermark tuner to darwin-mode.** Rejected by the anti-substitution rule β it would evolve TS surfaces, not detector params.+3. **Framework-first (extract traits before fixing the crate).** Rejected: the fixed-k* gate, the split, and the corrected meta-null are correctness fixes the crate needs regardless; bundling them with a six-trait rewrite delays a bug fix behind an abstraction whose payoff is contingent.+4. **Keep `null: Standardized` in the gate contract.** Rejected: leaks the replay shape; metaharness has no `null_mean/null_sd` β hence `NullEvidence`.+5. **`Metric::dominates` default = scalar.** Rejected: silently collapses metaharness's Pareto front (review finding 9); no default.+6. **Analytic-only guarantee (rely on Claim 1).** Rejected: vacuous at deployed |P|; the empirical split + meta-null is the operative control.++---++## Rollback++- **Phase 0 (in-crate correctness) rollback:** the fixed-k* gate, split, and meta-null are additive and feature-flagged (`WATERMARK_GOVERNED_GATE`); disabling reverts to `beats_selfsync()` point comparison (the current, weaker-but-known behavior). No data migration.+- **Speedups (1)** are byte-equivalence-tested; rollback = revert commits; no semantic change to undo.+- **Framework (2):** `ruflo-evolve` is a new crate; the watermark adapter can be reverted to the bespoke loop (kept behind a `git tag` snapshot) without touching consumers. The workspace `Cargo.toml` addition is the only shared-manifest change and is trivially revertible.+- **TS mirror / darwin adapter (4):** separate PRs in `agent-harness-generator`; abandon the PRs β no effect on ruflo. If darwin-mode declines the traits, Phase 2's extraction is retained for the single watermark caller only if a second Rust consumer materializes; otherwise revert the extraction and keep the crate-local governed loop.++---++## Open Questions++1. **Signal-adaptive proposer meta-null (adversarial J).** Can the meta-null be made provably selection-intensity-matched under a surrogate proposer, or must the calibrated guarantee be restricted to signal-independent proposers? (Currently: restricted; surrogate ships behind the split with a flagged residual.)+2. **Worst-case FP control (adversarial B/F).** Is there a valid sequential/permutation test *for the `neg_max` extreme functional itself*, so the FWER guarantee and the safety functional coincide, rather than relying on a separate hard floor?+3. **Hash idealization (adversarial, Claim 2 (ii)).** Can exchangeability be established without treating `mix64`/`context_seed` as a random oracle, or is the guarantee inherently heuristic outside that idealization?+4. **Stochastic-judge covering object (adversarial L).** What is the right complexity measure for a stochastic paid evaluator to recover a Claim-1-analogue, and what variance bound makes `fingerprint()` meaningful for grading stability?+5. **Adaptive-attacker benchmark refresh (adversarial N).** How to keep `E ~ D` under an adaptive watermark attacker so the selection guarantee approximates a deployment guarantee β an adversarial-benchmark cadence, out of scope for the error-control proof.+6. **darwin-mode adoption.** Will darwin-mode implement the TS traits? The framework's "one methodology" value is contingent on it (review finding 4); until then the guarantee is realized only for the watermark instance.+7. **Reserve/settle over-charge.** Does the two-phase ledger correctly settle a paid judge that charges on a mid-eval budget cross, or does a reservation strand real spend (review finding 2)?++---++## Implementation Plan++**Concurrency rule (load-bearing).** Concurrent multi-agent implementation into **`agent-harness-generator`** (which carries heavy pre-existing WIP) **must use isolated git worktrees + separate PRs β never parallel writers in one checkout.** Only the integration owner edits shared manifests (`Cargo.toml` workspace members, `v3/` `package.json`, `ruflo/package.json` overrides, lockfiles). Read-only agents may share a checkout; writing agents may not. Every phase binds its tests/benchmarks to an exact clean commit or an immutable dirty-worktree snapshot. Every phase ships **behind tests + a frozen benchmark**.++Legend: **[WT-ISO]** = worktree-isolated, safe for a dedicated writing agent in its own worktree Β· **[INT-OWNER]** = touches shared manifests, integration-owner-only.++### Phase 0 β In-crate correctness + wire the guarantee for the watermark instance **[WT-ISO β `crates/ruflo-watermark`]**+Addresses adversarial A, C, E, F, I, K and review finding 1. Ships independently of any abstraction.+- `crates/ruflo-watermark/src/align.rs`: extract `EmpiricalNullCalibrator` from `detect_gumbel_aligned` (lines 139-150); emit `p_perm` alongside `z`.+- `crates/ruflo-watermark/src/evolve.rs`:+ - **Independent-gate split** β add a distinct **gate seed B** to `Budget`; `score_with` gains a select/gate distinction; select on A, re-score winner + all references on B.+ - **Fixed-k\* gate re-score** β gate re-scores at a pre-registered `k*` (default 48), neutralizing the `null_replays` calibration-noise-selection channel (finding 1); `null_replays` remains evolvable during search only.+ - **Corrected meta-null** β new `signal_free_meta_null()`: re-run the whole evolution B times scoring against **wrong-key readings of the genuine watermarked-then-attacked positives** (nuisance-preserving); return `p_meta`.+ - **Governed promotion** β replace the informal `beats_selfsync()` decision with a first-class `PromotionReceipt`-shaped struct carrying `neg_max_z(B) < 4.0` **safety floor** + margin-vs-references(B) + `p_meta`; persist run seed + gate seed B. Feature-flag `WATERMARK_GOVERNED_GATE`.+- **Tests + frozen benchmark:** Evaluation-plan items 2, 3, 4, 5, 6 as `#[test]`s over a frozen `IndelBenchmark` seed; assert byte-repro of the governed verdict.++### Phase 1 β Exact speedups in the crate **[WT-ISO β `crates/ruflo-watermark`]**+Addresses optimizations {5, 4, 2a, 2b}. No semantic change.+- `align.rs`: per-item cache of `centered_scores` keyed by `(item, key-role)` (opt 5) with equality-assertion guard; state/exploit CRN (opt 2a); pre-registered control-variate Ξ² using the self-sync analytic proxy (opt 2b).+- `evolve.rs`: parallelize evaluation **across candidates** indexed by `(gen,child)`; keep intra-candidate folds fixed-order (opt 4).+- **Tests + frozen benchmark:** golden-master byte-equivalence (Evaluation item 1) β any float divergence fails CI.++### Phase 2 β Extract `ruflo-evolve` crate (six traits + driver + calibrator + budget) **[INT-OWNER for workspace manifest; WT-ISO for crate contents]**+Gated on a darwin-mode adoption commitment (Open Question 6).+- New crate `crates/ruflo-evolve`: `Genome`, `Metric` (no `dominates` default β finding 9), `FitnessEvaluator` with `reserve/settle` (finding 2), `LineageStore`, `PromotionGate` with mandatory `safety_floor`, `NullEvidence` enum (finding 5), `NuisancePreservingNull` + `EmpiricalNullCalibrator` (pluggable null estimator β finding 8), `Cost`/`Budget`, `Prng` (invariant relaxed to *search* randomness β finding 7), `SelectionStrategy`, `evolve()`.+- **[INT-OWNER]** add `crates/ruflo-evolve` to the workspace `Cargo.toml` members.+- **[WT-ISO]** re-express `ruflo-watermark` as an adapter implementing the six traits over `AlignParams`; delete the bespoke loop (kept behind a `git tag` for rollback).+- **Tests + frozen benchmark:** adapter reproduces Phase-0/1 governed verdicts byte-identically; Evaluation item 8 (bespoke-loop-deleted CI assertion).++### Phase 3 β Selection accelerators behind the split **[WT-ISO β `crates/ruflo-watermark` + `crates/ruflo-evolve`]**+Only after Phase 0's split + meta-null exist. Addresses optimizations {1, 2c-pruning, 3}.+- Successive halving (positives-only subsampling; full negatives β opt 1); adaptive replays in pruning only, fixed-k* at gate (opt 2c); surrogate EI proposer as a `SelectionStrategy` (opt 3) with its meta-null generated through the same surrogate + seed schedule.+- **Tests + frozen benchmark:** Evaluation item 3 re-run with halving in the pipeline; assert false-promotion β€ Ξ±; record the surrogate self-calibration residual (Open Question 1) as a measured caveat, not a pass.++### Phase 4 β TS mirror `@claude-flow/evolve` + darwin-mode adapter **[agent-harness-generator: WT-ISO worktrees + SEPARATE PRs; INT-OWNER for shared TS manifests]**+Heavy WIP repo β **isolated worktrees + separate PRs mandatory; no parallel writers in one checkout.**+- New package `@claude-flow/evolve` (TS): the six interfaces (async `FitnessEvaluator` β evaluator may be out-of-process/paid), `NullEvidence`, `calibrate`, `evolve`. Structural invariants documented as *convention* (interfaces cannot enforce them β review finding 4); byte-determinism and fingerprint-freeze explicitly marked Rust-only.+- `packages/darwin-mode/src` adapter (one agent per file, each in its own worktree/PR): `types.ts` β `Genome`/`Metric(Graded, Pareto dominates)`; `generator.ts`+sandboxes (`mock-sandbox.ts`, `tier2-sandbox.ts`) β `FitnessEvaluator` with `Cost{usd,tokens}` + `reserve/settle`; `archive.ts` β `LineageStore`; `scorer.ts` gate + `bench/{runner,stats,risk}.ts` β `PromotionGate` with `NullEvidence::Bootstrap` + BH-FDR + SGM + signed-promote; `evolve.ts` β thin driver call.+- **[INT-OWNER]** `v3/` `package.json` + `ruflo/package.json` overrides for the new package.+- **Tests + frozen benchmark:** Evaluation item 7 (reproduce the ADR-099 empirical-FDR audit through the new gate path).++### Phase 5 β Governance wiring **[WT-ISO per repo; INT-OWNER for signing-key policy]**+- Ed25519 `PromotionReceipt` signing behind the policy-held key (ADR-322 model) in both `ruflo-evolve` (Rust) and `@claude-flow/evolve` (TS); human-gate CLI surface; `NullEvidence::Absent`-on-Promote rejected at the gate.+- **Tests + frozen benchmark:** a Promote without valid `NullEvidence` and without passing `safety_floor` is refused; signed receipts verify against the public key.++**Cross-phase discipline:** bind every test/benchmark to an exact clean commit or immutable snapshot; only the integration owner reconciles overlapping changes or edits shared manifests; continue independent local work after spawning agents and wait only on real dependencies (Phase 2 depends on 0/1; Phase 3 depends on 0; Phase 4 depends on 2's spec but not its Rust code; Phase 5 depends on 2 and 4).\ No newline at end of file