gameplay: port filter metadata update policy

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

@@ -80,6 +80,10 @@ fn main() {
     assert_eq!(w.len(), 5 + l + 3 * n);
     let mut records = rows(&w[5 + l..]);
     match kind.as_str() {
+        "metadata" => {
+            let p = update_filter_metadata(&mut records, &text, w[1], w[2] as i32).unwrap();
+            println!("{}", mutation_json(p, &records, vec![]));
+        }
         "remove" => {
             let p = remove_filter(&mut records, &text).unwrap();
             println!("{}", mutation_json(p, &records, vec![]));

crates/urt-gameplay/src/filter_lifecycle.rs

@@ -140,3 +140,81 @@ mod removal_tests {
         assert_eq!(rows, before);
     }
 }
+
+/// Original252127 replaces only metadata on the first exact mask/comparison
+/// match; a nonzero save argument requests export after that successful write.
+pub fn update_filter_metadata(
+    records: &mut [FilterRecord],
+    text: &[u8],
+    metadata: u32,
+    save: i32,
+) -> Result<FilterMutation, Error> {
+    if records.len() > 4096 {
+        return Err(Error::InvalidCount);
+    }
+    let parsed = crate::native_policy::parse_filter(text)?;
+    let mut notices = vec![];
+    let mut found = false;
+    match parsed {
+        Err(remaining) => notices.push(FilterNotice::BadAddress(remaining)),
+        Ok((mask, comparison)) => {
+            if let Some(row) = records
+                .iter_mut()
+                .find(|r| r.mask == mask && r.comparison == comparison)
+            {
+                row.metadata = metadata;
+                found = true;
+            } else {
+                notices.push(FilterNotice::NotFound(
+                    text.split(|b| *b == 0).next().unwrap_or_default().to_vec(),
+                ));
+            }
+        }
+    }
+    Ok(FilterMutation {
+        result: found,
+        notices,
+        export: found && save != 0,
+    })
+}
+#[cfg(test)]
+mod metadata_tests {
+    use super::*;
+    #[test]
+    fn only_first_metadata_changes_and_negative_save_exports() {
+        let row = FilterRecord {
+            mask: u32::MAX,
+            comparison: 0x04030201,
+            metadata: 9,
+        };
+        let mut rows = [row, row];
+        let p = update_filter_metadata(&mut rows, b"1.2.3.4", 0x80000000, -1).unwrap();
+        assert!(p.result && p.export);
+        assert!(p.notices.is_empty());
+        assert_eq!(rows[0].metadata, 0x80000000);
+        assert_eq!(rows[0].comparison, row.comparison);
+        assert_eq!(rows[0].mask, row.mask);
+        assert_eq!(rows[1], row);
+    }
+    #[test]
+    fn no_save_and_parse_errors_do_not_request_export() {
+        let mut rows = [FilterRecord {
+            mask: u32::MAX,
+            comparison: u32::MAX,
+            metadata: 9,
+        }];
+        let p = update_filter_metadata(&mut rows, b"255.255.255.255", 42, 0).unwrap();
+        assert!(p.result);
+        assert!(!p.export);
+        assert_eq!(rows[0].comparison, u32::MAX);
+        let before = rows;
+        assert!(update_filter_metadata(&mut rows, &[b'1'; 128], 7, 1).is_err());
+        assert_eq!(rows, before);
+        assert!(
+            !update_filter_metadata(&mut rows, b"bad", 7, 1)
+                .unwrap()
+                .export
+        );
+        assert_eq!(rows, before);
+    }
+}

docs/FINDINGS.md

@@ -1809,3 +1809,5 @@ RE-936: Thirty actual253296 cases execute parser252304/37159, scan exact mask/co
 RE-937: Rust matches all30 original removal cases, retaining first-match ordering, unchanged mask/metadata/count, repeated sentinel matches, parser diagnostics and conditional export requests. Unsupported token domains fail atomically. Unit tests cover duplicate preservation and unsupported input without mutation; native export remains captured at this stage. [Evidence](research/RUST_FILTER_REMOVE.md).
 
 RE-938: Across180 actual252127 fixtures, parser252304/37159 precedes an exact mask/comparison scan; only the first match receives the supplied raw metadata word. Comparison/mask/count remain unchanged. Export is requested only after a successful match with a nonzero save argument. Invalid parse and missing match return0 with diagnostics. A comparison-1 sentinel can match and receive metadata without becoming active; timestamp interpretation and native callers remain open. [Evidence](research/QVM_FILTER_METADATA.md).
+
+RE-939: Rust matches180 original metadata-update cases, retaining the first exact pair, every unaffected row, raw metadata bits, parser/missing-match diagnostics and save gating. Unit tests verify negative save requests, duplicate preservation, sentinel matching and atomic rejection of unsupported tokens. Metadata is deliberately a raw word; native time/expiry interpretation remains open. [Evidence](research/RUST_FILTER_METADATA.md).

docs/PROVISIONAL_TODO.md

@@ -1855,3 +1855,5 @@ RE-924–933 completed bounded bot settings, announcement, connect-child composi
 - [x] RE-937 Rust exact-match filter removal and diagnostics ([evidence](research/RUST_FILTER_REMOVE.md)).
 
 - [x] RE-938 Original filter metadata update and save gating ([evidence](research/QVM_FILTER_METADATA.md)).
+
+- [x] RE-939 Rust first-match filter metadata policy ([evidence](research/RUST_FILTER_METADATA.md)).

docs/RESEARCH_LEDGER.md

@@ -2417,3 +2417,7 @@ Rust matches all30 original removal cases, retaining first-match ordering, uncha
 ## 2026-10-28 — RE-938 Original filter metadata update and save gating
 
 Across180 actual252127 fixtures, parser252304/37159 precedes an exact mask/comparison scan; only the first match receives the supplied raw metadata word. Comparison/mask/count remain unchanged. Export is requested only after a successful match with a nonzero save argument. Invalid parse and missing match return0 with diagnostics. A comparison-1 sentinel can match and receive metadata without becoming active; timestamp interpretation and native callers remain open. Focused `cargo xtask test-group qvm-filter-metadata` 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-939 Rust first-match filter metadata policy
+
+Rust matches180 original metadata-update cases, retaining the first exact pair, every unaffected row, raw metadata bits, parser/missing-match diagnostics and save gating. Unit tests verify negative save requests, duplicate preservation, sentinel matching and atomic rejection of unsupported tokens. Metadata is deliberately a raw word; native time/expiry interpretation remains open. Focused `cargo xtask test-group rust-filter-metadata` 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

@@ -1892,3 +1892,5 @@ Purpose: turn the supplied installation into an evidence-backed specification of
 - [x] RE-937 Rust exact-match filter removal and diagnostics ([evidence](research/RUST_FILTER_REMOVE.md)).
 
 - [x] RE-938 Original filter metadata update and save gating ([evidence](research/QVM_FILTER_METADATA.md)).
+
+- [x] RE-939 Rust first-match filter metadata policy ([evidence](research/RUST_FILTER_METADATA.md)).

docs/research/README.md

@@ -1427,3 +1427,5 @@ The extension collector adds five focused tests for native tail calls, command-r
 - [RE-937: Rust exact-match filter removal and diagnostics](RUST_FILTER_REMOVE.md).
 
 - [RE-938: Original filter metadata update and save gating](QVM_FILTER_METADATA.md).
+
+- [RE-939: Rust first-match filter metadata policy](RUST_FILTER_METADATA.md).

docs/research/RUST_FILTER_METADATA.md

@@ -0,0 +1,5 @@
+# Rust first-match filter metadata policy
+
+RE-939. Focused validation: `cargo xtask test-group rust-filter-metadata`. [Machine report](rust-filter-metadata.json).
+
+Rust matches180 original metadata-update cases, retaining the first exact pair, every unaffected row, raw metadata bits, parser/missing-match diagnostics and save gating. Unit tests verify negative save requests, duplicate preservation, sentinel matching and atomic rejection of unsupported tokens. Metadata is deliberately a raw word; native time/expiry interpretation remains open.

docs/research/rust-health-impulse.json

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

scripts/analyze_rust_filter_metadata.py

@@ -0,0 +1,18 @@
+"""Compare the Rust filter policy with the original QVM report."""
+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-policy'],check=True,capture_output=True)
+ binary=Path(os.environ.get('CARGO_TARGET_DIR','target'))/'debug'/'urt-filter-policy'
+ path=Path('docs/research/qvm-filter-metadata.json');data=path.read_bytes();probes=[]
+ for p in json.loads(data)['probes']:
+  a=p['input'];words=encode(a)
+  probes.append(dict(source={k:p[k] for k in ['result', 'diagnostics', 'exports', 'exported', 'rows']},rust=result(binary,'metadata',words)))
+ write_json(Path('docs/research/rust-filter-metadata.json'),dict(source_report=str(path),source_report_sha256=hashlib.sha256(data).hexdigest(),probes=probes,limits='Finite recovered policy parity; native filesystem/network effects are not executed.'))
+
+def encode(a):
+ text=bytes.fromhex(a['text']);return [len(a['rows']),a['metadata'],a['save'],a['handle'],len(text),*text,*[v for r in a['rows'] for v in r]]
+if __name__=='__main__':main()

scripts/test_rust_filter_metadata.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-metadata.json').read_text());self.assertGreaterEqual(len(r['probes']),18)
+  for p in r['probes']:self.assertEqual(p['source'],p['rust'])
+ def test_identity(self):
+  r=json.loads(Path('docs/research/rust-filter-metadata.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

@@ -3146,3 +3146,17 @@ report	scripts/analyze_qvm_filter_metadata.py	docs/research/qvm-filter-metadata.
 edge	docs/research/qvm-filter-metadata.json	scripts/test_qvm_filter_metadata.py
 group	qvm-filter-metadata	scripts/analyze_qvm_filter_metadata.py
 edge	scripts/analyze_qvm_filter_metadata.py	scripts/analyze_qvm_resumer_audit.py
+report	scripts/analyze_rust_filter_metadata.py	docs/research/rust-filter-metadata.json
+edge	docs/research/rust-filter-metadata.json	scripts/test_rust_filter_metadata.py
+group	rust-filter-metadata	scripts/analyze_rust_filter_metadata.py
+edge	scripts/analyze_rust_filter_metadata.py	scripts/analyze_qvm_resumer_audit.py
+edge	Cargo.toml	scripts/analyze_rust_filter_metadata.py
+edge	Cargo.lock	scripts/analyze_rust_filter_metadata.py
+edge	crates/urt-gameplay/Cargo.toml	scripts/analyze_rust_filter_metadata.py
+edge	crates/urt-gameplay/src/lib.rs	scripts/analyze_rust_filter_metadata.py
+edge	crates/urt-gameplay/src/filter_lifecycle.rs	scripts/analyze_rust_filter_metadata.py
+edge	crates/urt-gameplay/src/native_policy.rs	scripts/analyze_rust_filter_metadata.py
+edge	crates/urt-gameplay/src/bin/urt-filter-policy.rs	scripts/analyze_rust_filter_metadata.py
+edge	docs/research/qvm-filter-metadata.json	scripts/analyze_rust_filter_metadata.py
+group	rust-filter-metadata	scripts/analyze_rust_health_impulse.py
+group	gameplay	scripts/analyze_rust_filter_metadata.py