gameplay: port add-filter command and queued kick

crates/urt-gameplay/src/bin/urt-filter-commands.rs

@@ -0,0 +1,131 @@
+use urt_gameplay::filter_commands::*;
+use urt_gameplay::native_policy::FilterRecord;
+fn hex(v: &[u8]) -> String {
+    v.iter().map(|v| format!("{v:02x}")).collect()
+}
+fn blob(w: &[u32], p: &mut usize) -> Vec<u8> {
+    let n = w[*p] as usize;
+    *p += 1;
+    let b = w[*p..*p + n].iter().map(|v| *v as u8).collect();
+    *p += n;
+    b
+}
+fn row_json(r: FilterRecord) -> String {
+    format!("[{},{},{}]", r.mask, r.comparison, r.metadata)
+}
+fn diagnostics(d: &[CommandDiagnostic]) -> String {
+    d.iter()
+        .map(|d| match d {
+            CommandDiagnostic::Full => r#"{"op":"full"}"#.into(),
+            CommandDiagnostic::Removed => r#"{"op":"removed"}"#.into(),
+            CommandDiagnostic::BadAddress(t) => {
+                format!(r#"{{"op":"bad-address","text":"{}"}}"#, hex(t))
+            }
+            CommandDiagnostic::NotFound(t) => {
+                format!(r#"{{"op":"not-found","text":"{}"}}"#, hex(t))
+            }
+        })
+        .collect::<Vec<String>>()
+        .join(",")
+}
+fn children_json(children: &[CommandChild]) -> String {
+    children
+        .iter()
+        .map(|p| {
+            format!(
+                r#"{{"result":{},"diagnostics":[{}],"exports":[{}]}}"#,
+                u8::from(p.result),
+                diagnostics(&p.diagnostics),
+                if p.export { "252500" } else { "" }
+            )
+        })
+        .collect::<Vec<_>>()
+        .join(",")
+}
+fn command_json(
+    p: FilterCommand,
+    rows: &[FilterRecord],
+    count: usize,
+    ring: u32,
+    selector: u32,
+) -> String {
+    let events = p
+        .effects
+        .iter()
+        .map(|e| match e {
+            FilterCommandEffect::Console(t) => format!(r#"{{"op":"console","text":"{}"}}"#, hex(t)),
+            FilterCommandEffect::Send { recipient, text } => format!(
+                r#"{{"op":"send","recipient":{},"text":"{}"}}"#,
+                recipient,
+                hex(text)
+            ),
+            FilterCommandEffect::Userinfo(slot) => {
+                format!(r#"{{"op":"userinfo","slot":{}}}"#, slot)
+            }
+            FilterCommandEffect::Insert { text, save } => format!(
+                r#"{{"op":"insert","text":"{}","save":{}}}"#,
+                hex(text),
+                save
+            ),
+            FilterCommandEffect::Remove(t) => format!(r#"{{"op":"remove","text":"{}"}}"#, hex(t)),
+            FilterCommandEffect::Enqueue { mode, text } => format!(
+                r#"{{"op":"enqueue","mode":{},"text":"{}"}}"#,
+                mode,
+                hex(text)
+            ),
+        })
+        .collect::<Vec<_>>()
+        .join(",");
+    format!(
+        r#"{{"events":[{}],"children":[{}],"ring":{},"selector":{},"count":{},"rows":[{}]}}"#,
+        events,
+        children_json(&p.children),
+        ring,
+        selector,
+        count,
+        rows.iter()
+            .copied()
+            .map(row_json)
+            .collect::<Vec<_>>()
+            .join(",")
+    )
+}
+fn main() {
+    let mut args = std::env::args().skip(1);
+    let kind = args.next().unwrap();
+    let w: Vec<u32> = args.map(|s| s.parse().unwrap()).collect();
+    match kind.as_str() {
+        "add" => {
+            let mut p = 2;
+            let text = blob(&w, &mut p);
+            let userinfo = blob(&w, &mut p);
+            assert_eq!(p, w.len());
+            let mut rows = vec![
+                FilterRecord {
+                    mask: 0x11223344,
+                    comparison: u32::MAX,
+                    metadata: 0x99aabbcc
+                };
+                8
+            ];
+            let mut count = 0;
+            let mut ring = u32::MAX;
+            let mut selector = 0;
+            let issuer = if w[0] == u32::MAX {
+                None
+            } else {
+                Some(w[0] as i32)
+            };
+            let input = FilterAddInput {
+                text: &text,
+                issuer,
+                active: &[w[1] as i32; 64],
+                userinfo: &userinfo,
+            };
+            let out =
+                add_filter_command(&mut rows, &mut count, input, &mut ring, &mut selector).unwrap();
+            println!("{}", command_json(out, &rows, count, ring, selector));
+        }
+        _ => panic!("unknown policy"),
+    }
+}

crates/urt-gameplay/src/filter_commands.rs

@@ -0,0 +1,268 @@
+//! Recovered filter command/caller policies; native effects remain explicit.
+use crate::filter_lifecycle::{FilterMutation, FilterNotice};
+use crate::native_policy::{
+    Error, FilterDiagnostic, FilterInsert, FilterRecord, info_lookup, insert_filter, signed_prefix,
+};
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum FilterCommandEffect {
+    Console(Vec<u8>),
+    Send { recipient: i32, text: Vec<u8> },
+    Userinfo(i32),
+    Insert { text: Vec<u8>, save: i32 },
+    Remove(Vec<u8>),
+    Enqueue { mode: i32, text: Vec<u8> },
+}
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum CommandDiagnostic {
+    Full,
+    BadAddress(Vec<u8>),
+    NotFound(Vec<u8>),
+    Removed,
+}
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct CommandChild {
+    pub result: bool,
+    pub diagnostics: Vec<CommandDiagnostic>,
+    pub export: bool,
+}
+impl From<FilterInsert> for CommandChild {
+    fn from(p: FilterInsert) -> Self {
+        Self {
+            result: p.result,
+            export: p.export,
+            diagnostics: p
+                .diagnostics
+                .into_iter()
+                .map(|d| match d {
+                    FilterDiagnostic::Full => CommandDiagnostic::Full,
+                    FilterDiagnostic::BadAddress(t) => CommandDiagnostic::BadAddress(t),
+                })
+                .collect(),
+        }
+    }
+}
+impl From<FilterMutation> for CommandChild {
+    fn from(p: FilterMutation) -> Self {
+        Self {
+            result: p.result,
+            export: p.export,
+            diagnostics: p
+                .notices
+                .into_iter()
+                .map(|d| match d {
+                    FilterNotice::Removed => CommandDiagnostic::Removed,
+                    FilterNotice::BadAddress(t) => CommandDiagnostic::BadAddress(t),
+                    FilterNotice::NotFound(t) => CommandDiagnostic::NotFound(t),
+                })
+                .collect(),
+        }
+    }
+}
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct FilterCommand {
+    pub effects: Vec<FilterCommandEffect>,
+    pub children: Vec<CommandChild>,
+}
+fn cbytes(v: &[u8]) -> &[u8] {
+    v.split(|b| *b == 0).next().unwrap_or_default()
+}
+fn format(
+    template: &[u8],
+    args: &[crate::qvm_format::Argument<'_>],
+    ring: &mut u32,
+) -> Result<Vec<u8>, Error> {
+    let mut text = crate::qvm_format::render(template, args).map_err(|_| Error::InvalidInput)?;
+    text.pop();
+    *ring = ring.wrapping_add(1);
+    Ok(text)
+}
+fn usage(issuer: Option<i32>, add: bool, ring: &mut u32) -> Result<FilterCommandEffect, Error> {
+    if let Some(recipient) = issuer {
+        let template = if add {
+            b"chat \"^5[rcon] ^7Usage: /addip <ip-mask>\"".as_slice()
+        } else {
+            b"chat \"^5[rcon] ^7Usage: /removeip <ip-mask>\"".as_slice()
+        };
+        Ok(FilterCommandEffect::Send {
+            recipient,
+            text: format(template, &[], ring)?,
+        })
+    } else {
+        Ok(FilterCommandEffect::Console(if add {
+            b"Usage: addip <ip-mask>\n".to_vec()
+        } else {
+            b"Usage: removeip <ip-mask>\n".to_vec()
+        }))
+    }
+}
+pub struct FilterAddInput<'a> {
+    pub text: &'a [u8],
+    pub issuer: Option<i32>,
+    pub active: &'a [i32; 64],
+    pub userinfo: &'a [u8],
+}
+/// Original253100: length<3 means client number, not necessarily numeric input.
+/// Active clients always queue a kick after insertion, including parse failures.
+pub fn add_filter_command(
+    records: &mut [FilterRecord],
+    count: &mut usize,
+    input: FilterAddInput<'_>,
+    ring: &mut u32,
+    selector: &mut u32,
+) -> Result<FilterCommand, Error> {
+    if records.len() > 4096 || *count > records.len() {
+        return Err(Error::InvalidCount);
+    }
+    if input.issuer.is_some_and(|v| !(0..64).contains(&v)) {
+        return Err(Error::InvalidIndex);
+    }
+    let text = cbytes(input.text);
+    if text.len() > 1024 {
+        return Err(Error::InvalidInput);
+    }
+    let mut staged = records.to_vec();
+    let mut next = *count;
+    let mut counter = *ring;
+    let mut info = *selector;
+    let mut effects = vec![];
+    let mut children = vec![];
+    if text.is_empty() {
+        effects.push(usage(input.issuer, true, &mut counter)?);
+    } else {
+        let mut client = None;
+        let address;
+        let ip = if text.len() < 3 {
+            let slot = signed_prefix(text);
+            if !(0..64).contains(&slot) || input.active[slot as usize] == 0 {
+                return Ok(FilterCommand { effects, children });
+            }
+            client = Some(slot);
+            effects.push(FilterCommandEffect::Userinfo(slot));
+            let raw = cbytes(input.userinfo);
+            let raw = &raw[..raw.len().min(1023)];
+            address = info_lookup(Some(raw), Some(b"ip"), &mut info)?.value;
+            address.as_slice()
+        } else {
+            text
+        };
+        effects.push(FilterCommandEffect::Insert {
+            text: ip.to_vec(),
+            save: 1,
+        });
+        children.push(insert_filter(&mut staged, &mut next, ip, 1)?.into());
+        if let Some(slot) = client {
+            let text = format(
+                b"clientkick %d\n",
+                &[crate::qvm_format::Argument::Word(slot)],
+                &mut counter,
+            )?;
+            effects.push(FilterCommandEffect::Enqueue { mode: 1, text });
+        }
+    }
+    records.copy_from_slice(&staged);
+    *count = next;
+    *ring = counter;
+    *selector = info;
+    Ok(FilterCommand { effects, children })
+}
+#[cfg(test)]
+mod add_tests {
+    use super::*;
+    fn row() -> FilterRecord {
+        FilterRecord {
+            mask: 7,
+            comparison: 8,
+            metadata: 9,
+        }
+    }
+    #[test]
+    fn missing_ip_and_full_table_still_queue_kick() {
+        let mut rows = [row()];
+        let mut count = 0;
+        let mut ring = u32::MAX;
+        let mut selector = 0;
+        let p = add_filter_command(
+            &mut rows,
+            &mut count,
+            FilterAddInput {
+                text: b"x",
+                issuer: None,
+                active: &[1; 64],
+                userinfo: b"\\name\\x",
+            },
+            &mut ring,
+            &mut selector,
+        )
+        .unwrap();
+        assert_eq!(count, 1);
+        assert_eq!(selector, 1);
+        assert_eq!(ring, 0);
+        assert!(matches!(
+            p.effects.last(),
+            Some(FilterCommandEffect::Enqueue { mode: 1, .. })
+        ));
+        assert!(!p.children[0].diagnostics.is_empty());
+        let mut rows = vec![row(); 4096];
+        count = 4096;
+        let p = add_filter_command(
+            &mut rows,
+            &mut count,
+            FilterAddInput {
+                text: b"0",
+                issuer: None,
+                active: &[1; 64],
+                userinfo: b"\\ip\\1.2.3.4",
+            },
+            &mut ring,
+            &mut selector,
+        )
+        .unwrap();
+        assert!(!p.children[0].result);
+        assert!(!p.children[0].export);
+        assert!(matches!(
+            p.effects.last(),
+            Some(FilterCommandEffect::Enqueue { .. })
+        ));
+    }
+    #[test]
+    fn inactive_client_does_nothing_and_unsupported_address_is_atomic() {
+        let mut rows = [row()];
+        let mut count = 0;
+        let mut ring = 7;
+        let mut selector = 0;
+        let p = add_filter_command(
+            &mut rows,
+            &mut count,
+            FilterAddInput {
+                text: b"63",
+                issuer: None,
+                active: &[0; 64],
+                userinfo: b"",
+            },
+            &mut ring,
+            &mut selector,
+        )
+        .unwrap();
+        assert!(p.effects.is_empty());
+        assert_eq!(rows, [row()]);
+        assert!(
+            add_filter_command(
+                &mut rows,
+                &mut count,
+                FilterAddInput {
+                    text: &[b'1'; 128],
+                    issuer: None,
+                    active: &[1; 64],
+                    userinfo: b""
+                },
+                &mut ring,
+                &mut selector
+            )
+            .is_err()
+        );
+        assert_eq!(rows, [row()]);
+        assert_eq!(count, 0);
+        assert_eq!(ring, 7);
+        assert_eq!(selector, 0);
+    }
+}

crates/urt-gameplay/src/lib.rs

@@ -185,3 +185,5 @@ pub mod native_policy;
 pub mod filter_lifecycle;
 
 pub mod filter_loading;
+
+pub mod filter_commands;

docs/FINDINGS.md

@@ -1841,3 +1841,5 @@ RE-952: Twenty-four actual export/reload compositions transfer captured file byt
 RE-953: Rust matches24 original export/reload compositions, retaining stale prior files when export is absent, all-hole truncation, wildcard-mask loss, INT_MIN metadata reload as0, duplicate routing and retained-table growth. The staged loader rejects unsupported domains without mutation. Unit tests cover these losses, duplicate growth and atomic unsupported prior-file rejection. Captured write bytes are supplied as read replies; actual filesystem acceptance remains open. [Evidence](research/RUST_FILTER_ROUNDTRIP.md).
 
 RE-954: Ninety-six actual253100 wrappers recover length-under3 client-number routing, active-slot gating, supplied1024-byte userinfo and actual70503 ip lookup, insertion and exact usage/kick formatting. Non-numeric short input can select slot0. A clientkick command is queued even after missing-ip insertion failure. Selector and formatter wraps, invalid slots and direct masks are verified; exports and native effects remain captured. [Evidence](research/QVM_FILTER_ADD_COMMAND.md).
+
+RE-955: Rust matches96 original add-filter command cases, retaining short-input numeric routing, active-slot/userinfo gates, selector toggles, exact usage/kick text and formatter wrap. Missing IP insertion failures still queue clientkick; an extra unit test verifies full-table refusal also queues a kick. Unsupported domains reject atomically. Native userinfo, queued commands, network and export remain captured plans. [Evidence](research/RUST_FILTER_ADD_COMMAND.md).

docs/PROVISIONAL_TODO.md

@@ -1891,3 +1891,5 @@ RE-934–943 completed bounded filter export/removal/metadata and insertion/remo
 RE-944–953 completed bounded time/expiry/loading/duration and export/reload contracts. RE-954 tracks remaining commands/callers, native ownership and runtime acceptance. [Batch and next work](research/QVM_FILTER_LOADING_BATCH.md).
 
 - [x] RE-954 Original add-filter client lookup and queued kick command ([evidence](research/QVM_FILTER_ADD_COMMAND.md)).
+
+- [x] RE-955 Rust add-filter wrapper and unconditional queued kick ([evidence](research/RUST_FILTER_ADD_COMMAND.md)).

docs/RESEARCH_LEDGER.md

@@ -2485,3 +2485,7 @@ Batch RE-944–953 boundary: the single `cargo xtask test-full --since ed9db0e6`
 ## 2026-10-28 — RE-954 Original add-filter client lookup and queued kick command
 
 Ninety-six actual253100 wrappers recover length-under3 client-number routing, active-slot gating, supplied1024-byte userinfo and actual70503 ip lookup, insertion and exact usage/kick formatting. Non-numeric short input can select slot0. A clientkick command is queued even after missing-ip insertion failure. Selector and formatter wraps, invalid slots and direct masks are verified; exports and native effects remain captured. Focused `cargo xtask test-group qvm-filter-add-command` passes with deterministic report regeneration, relevant regressions and storage/documentation/whitespace checks. Full suite deferred to the tenth-commit boundary. Original assets unchanged; native IO effects remain captured.
+
+## 2026-10-28 — RE-955 Rust add-filter wrapper and unconditional queued kick
+
+Rust matches96 original add-filter command cases, retaining short-input numeric routing, active-slot/userinfo gates, selector toggles, exact usage/kick text and formatter wrap. Missing IP insertion failures still queue clientkick; an extra unit test verifies full-table refusal also queues a kick. Unsupported domains reject atomically. Native userinfo, queued commands, network and export remain captured plans. Focused `cargo xtask test-group rust-filter-add-command` passes with deterministic report regeneration, relevant regressions and storage/documentation/whitespace checks. Full suite deferred to the tenth-commit boundary. Original assets unchanged; native IO effects remain captured.

docs/REVERSE_ENGINEERING_TODO.md

@@ -1928,3 +1928,5 @@ RE-944–953 recover bounded time, expiry, loading, duration and persistence rou
 - [ ] RE-954 Recover remaining filter commands/callers and native time/file/network ownership, bot setup/userinfo and full Rust/Bevy/Solari acceptance ([next work](research/QVM_FILTER_LOADING_BATCH.md)).
 
 - [x] RE-954 Original add-filter client lookup and queued kick command ([evidence](research/QVM_FILTER_ADD_COMMAND.md)).
+
+- [x] RE-955 Rust add-filter wrapper and unconditional queued kick ([evidence](research/RUST_FILTER_ADD_COMMAND.md)).

docs/research/README.md

@@ -1463,3 +1463,5 @@ The extension collector adds five focused tests for native tail calls, command-r
 - [RE-944–953 filter loading batch and RE-954 next work](QVM_FILTER_LOADING_BATCH.md).
 
 - [RE-954: Original add-filter client lookup and queued kick command](QVM_FILTER_ADD_COMMAND.md).
+
+- [RE-955: Rust add-filter wrapper and unconditional queued kick](RUST_FILTER_ADD_COMMAND.md).

docs/research/RUST_FILTER_ADD_COMMAND.md

@@ -0,0 +1,5 @@
+# Rust add-filter wrapper and unconditional queued kick
+
+RE-955. Focused validation: `cargo xtask test-group rust-filter-add-command`. [Machine report](rust-filter-add-command.json).
+
+Rust matches96 original add-filter command cases, retaining short-input numeric routing, active-slot/userinfo gates, selector toggles, exact usage/kick text and formatter wrap. Missing IP insertion failures still queue clientkick; an extra unit test verifies full-table refusal also queues a kick. Unsupported domains reject atomically. Native userinfo, queued commands, network and export remain captured plans.

docs/research/rust-health-impulse.json

@@ -2985,7 +2985,7 @@
       "exit_code": 2
     }
   ],
-  "rust_unit_tests": 209,
+  "rust_unit_tests": 211,
   "source_report": "docs/research/qvm-health-impulse.json",
   "source_report_sha256": "625fd8064004ea6dbdf398d51d0af844d9c635ff04c0a0790886dddb6ab81e71"
 }

scripts/analyze_rust_filter_add_command.py

@@ -0,0 +1,17 @@
+"""Compare recovered Rust policy with original QVM fixtures."""
+import hashlib,json,os,subprocess
+from pathlib import Path
+from analyze_qvm import write_json
+from rust_lifecycle_support import result
+
+def main():
+ subprocess.run(['cargo','build','--offline','--package','urt-gameplay','--bin','urt-filter-commands'],check=True,capture_output=True)
+ binary=Path(os.environ.get('CARGO_TARGET_DIR','target'))/'debug'/'urt-filter-commands'
+ path=Path('docs/research/qvm-filter-add-command.json');data=path.read_bytes();probes=[]
+ for p in json.loads(data)['probes']:
+  probes.append(dict(source={k:p[k] for k in ['events', 'children', 'ring', 'selector', 'count', 'rows']},rust=result(binary,'add',encode(p['input']))))
+ write_json(Path('docs/research/rust-filter-add-command.json'),dict(source_report=str(path),source_report_sha256=hashlib.sha256(data).hexdigest(),probes=probes,limits='Finite source/Rust contract parity; native time/file/network replies remain supplied or captured.'))
+
+def encode(a):
+ t=bytes.fromhex(a['text']);u=bytes.fromhex(a['userinfo']);return [a['issuer'],a['active'],len(t),*t,len(u),*u]
+if __name__=='__main__':main()

scripts/test_rust_filter_add_command.py

@@ -0,0 +1,9 @@
+import hashlib,json,unittest
+from pathlib import Path
+class PortTests(unittest.TestCase):
+ def test_original_parity(self):
+  r=json.loads(Path('docs/research/rust-filter-add-command.json').read_text());self.assertGreaterEqual(len(r['probes']),12)
+  for p in r['probes']:self.assertEqual(p['source'],p['rust'])
+ def test_identity(self):
+  r=json.loads(Path('docs/research/rust-filter-add-command.json').read_text());self.assertEqual(hashlib.sha256(Path(r['source_report']).read_bytes()).hexdigest(),r['source_report_sha256'])
+if __name__=='__main__':unittest.main()

xtask/checks.tsv

@@ -3308,3 +3308,23 @@ report	scripts/analyze_qvm_filter_add_command.py	docs/research/qvm-filter-add-co
 edge	docs/research/qvm-filter-add-command.json	scripts/test_qvm_filter_add_command.py
 group	qvm-filter-add-command	scripts/analyze_qvm_filter_add_command.py
 edge	scripts/analyze_qvm_filter_add_command.py	scripts/analyze_qvm_resumer_audit.py
+report	scripts/analyze_rust_filter_add_command.py	docs/research/rust-filter-add-command.json
+edge	docs/research/rust-filter-add-command.json	scripts/test_rust_filter_add_command.py
+group	rust-filter-add-command	scripts/analyze_rust_filter_add_command.py
+edge	scripts/analyze_rust_filter_add_command.py	scripts/analyze_qvm_resumer_audit.py
+edge	Cargo.toml	scripts/analyze_rust_filter_add_command.py
+edge	Cargo.lock	scripts/analyze_rust_filter_add_command.py
+edge	crates/urt-gameplay/Cargo.toml	scripts/analyze_rust_filter_add_command.py
+edge	crates/urt-gameplay/src/lib.rs	scripts/analyze_rust_filter_add_command.py
+edge	crates/urt-gameplay/src/filter_loading.rs	scripts/analyze_rust_filter_add_command.py
+edge	crates/urt-gameplay/src/filter_lifecycle.rs	scripts/analyze_rust_filter_add_command.py
+edge	crates/urt-gameplay/src/native_policy.rs	scripts/analyze_rust_filter_add_command.py
+edge	crates/urt-gameplay/src/bin/urt-filter-loading.rs	scripts/analyze_rust_filter_add_command.py
+edge	crates/urt-gameplay/src/qvm_format.rs	scripts/analyze_rust_filter_add_command.py
+edge	docs/research/qvm-filter-add-command.json	scripts/analyze_rust_filter_add_command.py
+group	rust-filter-add-command	scripts/analyze_rust_health_impulse.py
+group	gameplay	scripts/analyze_rust_filter_add_command.py
+edge	crates/urt-gameplay/src/filter_commands.rs	scripts/analyze_rust_filter_add_command.py
+edge	crates/urt-gameplay/src/bin/urt-filter-commands.rs	scripts/analyze_rust_filter_add_command.py
+edge	crates/urt-gameplay/src/filter_commands.rs	scripts/analyze_rust_health_impulse.py
+edge	crates/urt-gameplay/src/bin/urt-filter-commands.rs	scripts/analyze_rust_health_impulse.py