Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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/.gitignore
new file mode 100644
index 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.lock
new file mode 100644
index 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.toml
new file mode 100644
index 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 = 1
diff --git a/v3/crates/ruflo-watermark/benches/throughput.rs b/v3/crates/ruflo-watermark/benches/throughput.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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, &params);
+
+ // 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, &params));
+ }
+ 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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