gameplay: port filter expiration command effects

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

@@ -62,6 +62,7 @@ fn main() {
             );
         }
         "load" => println!("{}", loading(&w)),
+        "duration" => println!("{}", duration(&w)),
         _ => panic!("unknown policy"),
     }
 }
@@ -171,3 +172,71 @@ fn loading(w: &[u32]) -> String {
     .unwrap();
     load_json(out, &rows, count)
 }
+
+fn duration(w: &[u32]) -> String {
+    let mut pos = 3;
+    let address = blob(w, &mut pos);
+    let duration = blob(w, &mut pos);
+    assert_eq!(pos, w.len());
+    let fields = [13, w[0], 0, 4, 5, 126, 6, 0, 0];
+    let client = if w[1] == u32::MAX {
+        None
+    } else {
+        Some(w[1] as i32)
+    };
+    let mut ring = w[2];
+    let mut rows = [
+        urt_gameplay::native_policy::FilterRecord {
+            mask: u32::MAX,
+            comparison: 0x04030201,
+            metadata: 77,
+        },
+        urt_gameplay::native_policy::FilterRecord {
+            mask: u32::MAX,
+            comparison: 0x04030201,
+            metadata: 88,
+        },
+    ];
+    let p = filter_duration(&mut rows, &address, &duration, &fields, client, &mut ring).unwrap();
+    let effects = p
+        .effects
+        .iter()
+        .map(|e| match e {
+            FilterDurationEffect::Console(t) => {
+                format!(r#"{{"op":"console","text":"{}"}}"#, hex(t))
+            }
+            FilterDurationEffect::Send { recipient, text } => format!(
+                r#"{{"op":"send","recipient":{},"text":"{}"}}"#,
+                recipient,
+                hex(text)
+            ),
+            FilterDurationEffect::Time => r#"{"op":"time"}"#.into(),
+            FilterDurationEffect::Metadata { text, value } => format!(
+                r#"{{"op":"metadata","text":"{}","metadata":{},"save":1}}"#,
+                hex(text),
+                value
+            ),
+        })
+        .collect::<Vec<String>>()
+        .join(",");
+    let updates = p
+        .update
+        .map(|p| {
+            format!(
+                r#"{{"result":{},"diagnostics":[{}],"exports":[{}]}}"#,
+                u8::from(p.result),
+                notice_json(&p),
+                if p.export { "252500" } else { "" }
+            )
+        })
+        .unwrap_or_default();
+    let rows = rows
+        .iter()
+        .map(|r| list(&[r.mask, r.comparison, r.metadata]))
+        .collect::<Vec<_>>()
+        .join(",");
+    format!(
+        r#"{{"events":[{}],"updates":[{}],"ring":{},"rows":[{}]}}"#,
+        effects, updates, ring, rows
+    )
+}

crates/urt-gameplay/src/filter_loading.rs

@@ -295,3 +295,116 @@ mod load_tests {
         assert_eq!(count, old);
     }
 }
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum FilterDurationEffect {
+    Console(Vec<u8>),
+    Send { recipient: i32, text: Vec<u8> },
+    Time,
+    Metadata { text: Vec<u8>, value: u32 },
+}
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct FilterDuration {
+    pub effects: Vec<FilterDurationEffect>,
+    pub update: Option<FilterMutation>,
+}
+/// Original252213: empty arguments select usage; otherwise add parsed duration
+/// to supplied current minutes and request first-match metadata update with save.
+pub fn filter_duration(
+    records: &mut [FilterRecord],
+    address: &[u8],
+    duration: &[u8],
+    fields: &[u32; 9],
+    client: Option<i32>,
+    ring: &mut u32,
+) -> Result<FilterDuration, Error> {
+    if records.len() > 4096 {
+        return Err(Error::InvalidCount);
+    }
+    if client.is_some_and(|s| !(0..64).contains(&s)) {
+        return Err(Error::InvalidIndex);
+    }
+    let address = address.split(|b| *b == 0).next().unwrap_or_default();
+    let duration = duration.split(|b| *b == 0).next().unwrap_or_default();
+    if address.len() > 1024 || duration.len() > 1024 {
+        return Err(Error::InvalidInput);
+    }
+    if address.is_empty() || duration.is_empty() {
+        let effect = if let Some(recipient) = client {
+            let mut text = crate::qvm_format::render(
+                b"chat \"^5[rcon] ^7Usage: /addipexpire <ip-mask> <minutes>\"",
+                &[],
+            )
+            .map_err(|_| Error::InvalidInput)?;
+            text.pop();
+            *ring = ring.wrapping_add(1);
+            FilterDurationEffect::Send { recipient, text }
+        } else {
+            FilterDurationEffect::Console(b"Usage:  addipexpire <ip-mask> <minutes>\n".to_vec())
+        };
+        return Ok(FilterDuration {
+            effects: vec![effect],
+            update: None,
+        });
+    }
+    let value =
+        filter_minutes(fields).wrapping_add(crate::native_policy::signed_prefix(duration) as u32);
+    let mut staged = records.to_vec();
+    let update = update_filter_metadata(&mut staged, address, value, 1)?;
+    records.copy_from_slice(&staged);
+    Ok(FilterDuration {
+        effects: vec![
+            FilterDurationEffect::Time,
+            FilterDurationEffect::Metadata {
+                text: address.to_vec(),
+                value,
+            },
+        ],
+        update: Some(update),
+    })
+}
+#[cfg(test)]
+mod duration_tests {
+    use super::*;
+    #[test]
+    fn usage_wraps_only_client_ring_and_skips_time() {
+        let mut ring = u32::MAX;
+        let p = filter_duration(&mut [], b"", b"5", &[0; 9], Some(3), &mut ring).unwrap();
+        assert_eq!(ring, 0);
+        assert!(p.update.is_none());
+        assert!(matches!(
+            &p.effects[..],
+            [FilterDurationEffect::Send { recipient: 3, .. }]
+        ));
+        filter_duration(&mut [], b"1.2.3.4", b"", &[0; 9], None, &mut ring).unwrap();
+        assert_eq!(ring, 0);
+    }
+    #[test]
+    fn negative_duration_can_store_permanent_marker_and_preserves_duplicate() {
+        let row = FilterRecord {
+            mask: u32::MAX,
+            comparison: 0x04030201,
+            metadata: 77,
+        };
+        let mut rows = [row, row];
+        let mut ring = 7;
+        let p = filter_duration(&mut rows, b"1.2.3.4", b"-1", &[0; 9], None, &mut ring).unwrap();
+        assert!(p.update.unwrap().export);
+        assert_eq!(rows[0].metadata, u32::MAX);
+        assert_eq!(rows[1], row);
+        assert_eq!(ring, 7);
+    }
+    #[test]
+    fn unsupported_address_rejects_without_row_or_ring_changes() {
+        let row = FilterRecord {
+            mask: 7,
+            comparison: 8,
+            metadata: 9,
+        };
+        let mut rows = [row];
+        let mut ring = 7;
+        assert!(filter_duration(&mut rows, &[b'1'; 128], b"5", &[0; 9], None, &mut ring).is_err());
+        assert_eq!(rows, [row]);
+        assert_eq!(ring, 7);
+    }
+}

docs/FINDINGS.md

@@ -1833,3 +1833,5 @@ RE-948: Thirty-two original252933 fixtures compose actual insertion/metadata/par
 RE-949: Rust matches32 original loader compositions, preserving active count, first-prior-match metadata routing, short-read buffer provenance, NUL/line handling and unconditional read/close effects. The staged API accepts explicit declared length, delivered bytes, initial buffer and raw handle. It rejects unsafe negative lengths, overlong lines/tokens and insufficient table storage atomically. Unit tests cover duplicates, missing-file replies, stale partial reads and rollback after an unsupported later line. [Evidence](research/RUST_FILTER_LOAD.md).
 
 RE-950: Eighty actual252213 fixtures compose integer/time/metadata children, preserving wrapping duration-plus-current-minute arithmetic, exact first-match metadata writes and save requests. Empty arguments emit exact console or client usage without clock/update calls; client formatting advances and wraps the ring. Negative/overflowing duration prefixes are retained. Native clock/calendar semantics, sends and export execution remain explicit boundaries. [Evidence](research/QVM_FILTER_DURATION.md).
+
+RE-951: Rust matches80 original duration/usage command fixtures, preserving wrapping numeric prefixes, first-match metadata save requests, exact client/console text and formatter-counter wrap. Typed effects preserve time-before-update order; usage skips both. Unit tests cover client-only ring changes, negative duration producing permanent-1 metadata, duplicate preservation and atomic unsupported-address rejection. Native replies remain supplied or captured. [Evidence](research/RUST_FILTER_DURATION.md).

docs/PROVISIONAL_TODO.md

@@ -1881,3 +1881,5 @@ RE-934–943 completed bounded filter export/removal/metadata and insertion/remo
 - [x] RE-949 Rust bounded loading with explicit read replies ([evidence](research/RUST_FILTER_LOAD.md)).
 
 - [x] RE-950 Original expiration-duration command and usage paths ([evidence](research/QVM_FILTER_DURATION.md)).
+
+- [x] RE-951 Rust expiration command with typed time and usage effects ([evidence](research/RUST_FILTER_DURATION.md)).

docs/RESEARCH_LEDGER.md

@@ -2467,3 +2467,7 @@ Rust matches32 original loader compositions, preserving active count, first-prio
 ## 2026-10-28 — RE-950 Original expiration-duration command and usage paths
 
 Eighty actual252213 fixtures compose integer/time/metadata children, preserving wrapping duration-plus-current-minute arithmetic, exact first-match metadata writes and save requests. Empty arguments emit exact console or client usage without clock/update calls; client formatting advances and wraps the ring. Negative/overflowing duration prefixes are retained. Native clock/calendar semantics, sends and export execution remain explicit boundaries. Focused `cargo xtask test-group qvm-filter-duration` 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-951 Rust expiration command with typed time and usage effects
+
+Rust matches80 original duration/usage command fixtures, preserving wrapping numeric prefixes, first-match metadata save requests, exact client/console text and formatter-counter wrap. Typed effects preserve time-before-update order; usage skips both. Unit tests cover client-only ring changes, negative duration producing permanent-1 metadata, duplicate preservation and atomic unsupported-address rejection. Native replies remain supplied or captured. Focused `cargo xtask test-group rust-filter-duration` 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

@@ -1918,3 +1918,5 @@ RE-934–943 continue the prior batch with filter export/removal/metadata and co
 - [x] RE-949 Rust bounded loading with explicit read replies ([evidence](research/RUST_FILTER_LOAD.md)).
 
 - [x] RE-950 Original expiration-duration command and usage paths ([evidence](research/QVM_FILTER_DURATION.md)).
+
+- [x] RE-951 Rust expiration command with typed time and usage effects ([evidence](research/RUST_FILTER_DURATION.md)).

docs/research/README.md

@@ -1453,3 +1453,5 @@ The extension collector adds five focused tests for native tail calls, command-r
 - [RE-949: Rust bounded loading with explicit read replies](RUST_FILTER_LOAD.md).
 
 - [RE-950: Original expiration-duration command and usage paths](QVM_FILTER_DURATION.md).
+
+- [RE-951: Rust expiration command with typed time and usage effects](RUST_FILTER_DURATION.md).

docs/research/RUST_FILTER_DURATION.md

@@ -0,0 +1,5 @@
+# Rust expiration command with typed time and usage effects
+
+RE-951. Focused validation: `cargo xtask test-group rust-filter-duration`. [Machine report](rust-filter-duration.json).
+
+Rust matches80 original duration/usage command fixtures, preserving wrapping numeric prefixes, first-match metadata save requests, exact client/console text and formatter-counter wrap. Typed effects preserve time-before-update order; usage skips both. Unit tests cover client-only ring changes, negative duration producing permanent-1 metadata, duplicate preservation and atomic unsupported-address rejection. Native replies remain supplied or captured.

docs/research/rust-health-impulse.json

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

scripts/analyze_rust_filter_duration.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-loading'],check=True,capture_output=True)
+ binary=Path(os.environ.get('CARGO_TARGET_DIR','target'))/'debug'/'urt-filter-loading'
+ path=Path('docs/research/qvm-filter-duration.json');data=path.read_bytes();probes=[]
+ for p in json.loads(data)['probes']:
+  probes.append(dict(source={k:p[k] for k in ['events', 'updates', 'ring', 'rows']},rust=result(binary,'duration',encode(p['input']))))
+ write_json(Path('docs/research/rust-filter-duration.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):
+ ip=bytes.fromhex(a['address']);d=bytes.fromhex(a['duration']);return [a['now'],a['client'],a['ring'],len(ip),*ip,len(d),*d]
+if __name__=='__main__':main()

scripts/test_rust_filter_duration.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-duration.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-duration.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

@@ -3268,3 +3268,19 @@ report	scripts/analyze_qvm_filter_duration.py	docs/research/qvm-filter-duration.
 edge	docs/research/qvm-filter-duration.json	scripts/test_qvm_filter_duration.py
 group	qvm-filter-duration	scripts/analyze_qvm_filter_duration.py
 edge	scripts/analyze_qvm_filter_duration.py	scripts/analyze_qvm_resumer_audit.py
+report	scripts/analyze_rust_filter_duration.py	docs/research/rust-filter-duration.json
+edge	docs/research/rust-filter-duration.json	scripts/test_rust_filter_duration.py
+group	rust-filter-duration	scripts/analyze_rust_filter_duration.py
+edge	scripts/analyze_rust_filter_duration.py	scripts/analyze_qvm_resumer_audit.py
+edge	Cargo.toml	scripts/analyze_rust_filter_duration.py
+edge	Cargo.lock	scripts/analyze_rust_filter_duration.py
+edge	crates/urt-gameplay/Cargo.toml	scripts/analyze_rust_filter_duration.py
+edge	crates/urt-gameplay/src/lib.rs	scripts/analyze_rust_filter_duration.py
+edge	crates/urt-gameplay/src/filter_loading.rs	scripts/analyze_rust_filter_duration.py
+edge	crates/urt-gameplay/src/filter_lifecycle.rs	scripts/analyze_rust_filter_duration.py
+edge	crates/urt-gameplay/src/native_policy.rs	scripts/analyze_rust_filter_duration.py
+edge	crates/urt-gameplay/src/bin/urt-filter-loading.rs	scripts/analyze_rust_filter_duration.py
+edge	crates/urt-gameplay/src/qvm_format.rs	scripts/analyze_rust_filter_duration.py
+edge	docs/research/qvm-filter-duration.json	scripts/analyze_rust_filter_duration.py
+group	rust-filter-duration	scripts/analyze_rust_health_impulse.py
+group	gameplay	scripts/analyze_rust_filter_duration.py