Simplify state field filtering

Author: CryZe

TODO.md

@@ -27,18 +27,15 @@ General rules:
 - Remove completed work from this file during the next roadmap update and
   summarize the milestone in the archive.
 
-## Now — gate lifecycle evaluation without rolling back state
-
-- [ ] Add an explicit `shouldEvaluate` lifecycle block returning `bool` and
-  defaulting to `true`. It runs after snapshot commit and `whileAttached`; a
-  false result skips `isLoading`, `gameTime`, `reset`, `split`, and `start` for
-  that tick without rolling back state or suppressing ordinary per-tick work.
-- [ ] Port a representative ASL script whose boolean `update` block returns
-  false, and verify host-executed ordering for snapshot rotation,
-  `whileAttached`, the evaluation gate, and timer decisions.
-- [ ] Document the distinction between state-read failure, per-field
-  `normalize`, and `shouldEvaluate`, with focused migration diagnostics for an
-  ASL `update { return false; }` pattern.
+## Now — unblock the next representative native port
+
+- [ ] Select the next manually reviewed ASL port whose blocker is shared by
+  multiple scripts, then implement the smallest ordinary language or
+  source-defined standard-library feature that makes the port faithful.
+- [ ] Keep boolean ASL `update { return false; }` behavior as corpus evidence,
+  but do not introduce a dedicated lifecycle keyword or block until a
+  maintained port proves that state-field expressions and `whileAttached`
+  cannot represent the behavior clearly.
 
 ## P0 — unblock the next representative native ports
 

crates/splitscript-syntax/src/ast.rs

@@ -537,18 +537,18 @@ pub struct StateField {
     pub documentation: Option<String>,
     pub annotation: Option<TypeRef>,
     pub source: StateSource,
-    pub normalizer: Option<StateNormalizer>,
+    pub transform: Option<StateTransform>,
     pub span: Span,
 }
 
-/// A pure transformation applied to one successfully read state-field value
-/// before the transactional snapshot is committed.
+/// An optional ordinary expression that selects the value committed for one
+/// successfully read state-field candidate.
 #[derive(Debug, Clone)]
-pub struct StateNormalizer {
+pub struct StateTransform {
     /// Implicit `value` binding containing the newly read candidate.
     pub value: ValueId,
-    /// Implicit `previous` binding containing the last accepted value.
-    pub previous: ValueId,
+    /// Implicit `old` binding containing the last accepted value.
+    pub old: ValueId,
     pub expression: Expr,
     pub span: Span,
 }

crates/splitscript-syntax/src/migration.rs

@@ -410,11 +410,8 @@ pub const CONCEPTS: &[MigrationConcept] = &[
         name: "MemoryWatcher",
         sources: ASL,
         support: MigrationSupport::TypedPattern,
-        summary: "Declare polled memory in `state`; use per-field `normalize` when a transient candidate should retain its last accepted value.",
-        targets: &[
-            MigrationTarget::Language("state"),
-            MigrationTarget::Language("normalize"),
-        ],
+        summary: "Declare polled memory in `state`; use a trailing field `if` with `value` and `old` when a transient candidate should retain its last accepted value.",
+        targets: &[MigrationTarget::Language("state")],
         cookbook_anchor: Some("retaining-the-last-accepted-field-value"),
         spellings: &[],
     },

crates/splitscript-syntax/src/parser.rs

@@ -16,8 +16,8 @@ use crate::{
         Parameter, PatternBinding, PatternId, PointerPath, Program, RecordDecl, RecordField,
         RecordFieldId, RecordId, ResultTypeDecl, ResultTypeId, SettingChoiceOption,
         SettingChoiceOptionId, SettingDecl, SettingExternalKey, SettingFileFilter, SettingKind,
-        Span, StateDecl, StateField, StateLayoutDecl, StateMemoryDecoder, StateNormalizer,
-        StateProviderRef, StateSource, Stmt, SuspensionMode, TypeNameId, TypeRef, UnaryOp, ValueId,
+        Span, StateDecl, StateField, StateLayoutDecl, StateMemoryDecoder, StateProviderRef,
+        StateSource, StateTransform, Stmt, SuspensionMode, TypeNameId, TypeRef, UnaryOp, ValueId,
         VariableDecl,
     },
     diagnostic::Diagnostic,

crates/splitscript-syntax/src/parser/declarations.rs

@@ -6,8 +6,8 @@ use super::{
     Action, ActionKind, Diagnostic, EnumDecl, EnumId, EnumReference, EnumVariant, FunctionDecl,
     FunctionId, Parameter, Parser, PointerPath, RecordDecl, RecordField, RecordId,
     SettingChoiceOption, SettingDecl, SettingExternalKey, SettingFileFilter, SettingKind, Span,
-    StateDecl, StateField, StateLayoutDecl, StateMemoryDecoder, StateNormalizer, StateProviderRef,
-    StateSource, TokenKind, TypeRef,
+    StateDecl, StateField, StateLayoutDecl, StateMemoryDecoder, StateProviderRef, StateSource,
+    StateTransform, TokenKind, TypeRef,
 };
 use crate::{
     diagnostic::{DiagnosticFix, FixApplicability, TextEdit},
@@ -494,28 +494,30 @@ impl Parser<'_> {
                 decoder,
             })
         };
-        let normalizer = self.eat_ident("normalize").map(|start| {
-            let value = self.new_value_id();
-            let previous = self.new_value_id();
-            let expression = self.root_expression();
-            StateNormalizer {
-                value,
-                previous,
-                span: Span {
-                    start: start.start,
-                    end: expression.span.end,
-                },
-                expression,
-            }
-        });
+        let transform =
+            (matches!(&source, StateSource::Pointer(_)) && self.at_ident("if")).then(|| {
+                let start = self.current().span;
+                let value = self.new_value_id();
+                let old = self.new_value_id();
+                let expression = self.root_expression();
+                StateTransform {
+                    value,
+                    old,
+                    span: Span {
+                        start: start.start,
+                        end: expression.span.end,
+                    },
+                    expression,
+                }
+            });
         let end = self.previous().span.end;
         Ok(StateField {
             id: self.new_value_id(),
             name,
             documentation,
             annotation,
             source,
-            normalizer,
+            transform,
             span: Span {
                 start: field_start.start,
                 end,
@@ -998,7 +1000,7 @@ impl Parser<'_> {
                         offsets,
                         decoder: None,
                     }),
-                    normalizer: None,
+                    transform: None,
                     span: Span {
                         start: field_start.start,
                         end,

crates/splitscript-syntax/src/visit.rs

@@ -141,8 +141,8 @@ pub fn walk_state_field<'ast, V: Visitor<'ast>>(visitor: &mut V, field: &'ast St
     if let StateSource::Expression(expression) = &field.source {
         visitor.visit_expr(expression);
     }
-    if let Some(normalizer) = &field.normalizer {
-        visitor.visit_expr(&normalizer.expression);
+    if let Some(transform) = &field.transform {
+        visitor.visit_expr(&transform.expression);
     }
 }
 
@@ -477,8 +477,8 @@ pub fn walk_state_field_mut<F: Folder>(folder: &mut F, field: &mut StateField) {
     if let StateSource::Expression(expression) = &mut field.source {
         folder.fold_expr(expression);
     }
-    if let Some(normalizer) = &mut field.normalizer {
-        folder.fold_expr(&mut normalizer.expression);
+    if let Some(transform) = &mut field.transform {
+        folder.fold_expr(&mut transform.expression);
     }
 }
 

docs/ASL_PORTING.md

@@ -144,33 +144,34 @@ the sentinel into a failed state read: a failed read rejects every field in the
 transaction, while the original script may still accept unrelated values from
 that tick.
 
-Use a field normalizer instead:
+Use an ordinary trailing `if` on that pointer-path field instead:
 
 ```splitscript
 state "game.exe" {
-    scene: i32 at "engine.dll", 0x1000 normalize if value == 7 || value == 8 {
-        previous
+    scene: i32 at "engine.dll", 0x1000 if value == 7 || value == 8 {
+        old
     } else {
         value
     };
     entities: i32 at "engine.dll", 0x2000;
 }
 ```
 
-`value` is the successfully read candidate and `previous` is the last value
+`value` is the successfully read candidate and `old` is the last value
 accepted for that field. Both are read-only and have the field's inferred
 type. On the first successful poll after each attachment, both names contain
 the candidate, so no stale value leaks across processes. Each field is
-normalized independently and then the complete resulting snapshot commits
+filtered independently and then the complete resulting snapshot commits
 atomically.
 
 The maintained
 [`examples/aawcb.split`](../examples/aawcb.split) port uses this to retain its
 scene during loading scenes 7 and 8 while the entity count continues to
 advance. By contrast, an ASL `update` block that returns `false` does not roll
-back state at all; it skips lifecycle decisions after the refresh. That pattern
-will map to the separate `shouldEvaluate` lifecycle gate rather than
-`normalize`.
+back state at all; it skips lifecycle decisions after the refresh. SplitScript
+does not add a separate lifecycle concept for that behavior until a maintained
+port demonstrates that ordinary field expressions and `whileAttached` cannot
+represent the required result clearly.
 
 ## Run-scoped one-shot splits
 

docs/LANGUAGE.md

@@ -60,25 +60,27 @@ Only when every required field succeeds does it rotate `current` to `old` and
 commit the candidate as `current`. The fields form a WebAssembly GC struct, so
 the action code uses typed references rather than a linear-memory state layout.
 
-A field can normalize its successful raw candidate before that atomic commit:
+A pointer-path field can use an ordinary trailing `if` expression to choose the
+value that is accepted before that atomic commit. Expression-backed fields
+already have an ordinary right-hand side and should put the `if` there instead:
 
 ```text
 state "game.exe" {
-    scene: i32 at 0x1000 normalize if value == 7 || value == 8 {
-        previous
+    scene: i32 at 0x1000 if value == 7 || value == 8 {
+        old
     } else {
         value
     };
     entities: i32 at 0x2000;
 }
 ```
 
-Inside `normalize`, the read-only `value` and `previous` bindings both have the
-field's inferred type. `value` is the raw candidate; `previous` is the last
-committed value for that field. On the first successful poll after attachment,
-both are the raw candidate. Normalization is per field, so retaining `scene`
-does not discard a new `entities` value from the same otherwise-valid tick.
-`current` and `old` stay read-only.
+Inside this field-local expression, the read-only `value` and `old` bindings
+both have the field's inferred type. `value` is the raw candidate; `old` is the
+last committed value for that field. On the first successful poll after
+attachment, both are the raw candidate. The expression applies to one field,
+so retaining `scene` does not discard a new `entities` value from the same
+otherwise-valid tick. Snapshot `current` and `old` values stay read-only.
 
 Games with multiple supported memory layouts can name each layout inside one
 state declaration. Fields present in every layout with a compatible type form

docs/MIGRATION_CAPABILITIES.md

@@ -14,7 +14,7 @@ This index maps common source-language concepts to canonical SplitScript APIs an
 | `asl.state.string-n` — Bounded native stringN state | ASL | Use a typed pattern | Use an explicitly decoded state path such as `as utf8(50)`; choose the encoding from evidence. Canonical targets: `state`. [Recipe](ASL_PORTING.md#bounded-native-stringn-state). |
 | `asl.state.version-label` — Version-labelled state blocks | ASL | Use a typed pattern | Use named layouts in one state block and return the selected layout from `onAttach`. Canonical targets: `state`. [Recipe](ASL_PORTING.md#version-labelled-asl-states). |
 | `asl.memory.deep-pointer` — DeepPointer | ASL | Supported directly | Use typed state paths for polled fields or `process.follow` for discovered paths. Canonical targets: `state`, `Process.follow`. |
-| `asl.state.memory-watcher` — MemoryWatcher | ASL | Use a typed pattern | Declare polled memory in `state`; use per-field `normalize` when a transient candidate should retain its last accepted value. Canonical targets: `state`, `normalize`. [Recipe](ASL_PORTING.md#retaining-the-last-accepted-field-value). |
+| `asl.state.memory-watcher` — MemoryWatcher | ASL | Use a typed pattern | Declare polled memory in `state`; use a trailing field `if` with `value` and `old` when a transient candidate should retain its last accepted value. Canonical targets: `state`. [Recipe](ASL_PORTING.md#retaining-the-last-accepted-field-value). |
 | `asl.timer.on-start` — timer.OnStart | ASL | Use a typed pattern | Observe the `timer.state()` transition in `whileAttached` and reset run-scoped script state there. Canonical targets: `whileAttached`, `timer.state`. [Recipe](ASL_PORTING.md#run-scoped-one-shot-splits). |
 | `asl.lifecycle.exit` — exit game-time cleanup | ASL | Supported directly | Use guarded `onDetached` cleanup and `timer.pauseGameTime()`. Canonical targets: `onDetached`, `timer.pauseGameTime`. [Recipe](ASL_PORTING.md#process-exit-game-time-cleanup). |
 | `asl.settings.dynamic-lookup` — Dynamic settings lookup | ASL | Supported directly | Declare an exact string key with `key "..."`, then use `settings.enabled(key)` or `oldSettings.enabled(key)` for boolean settings. Choice and file settings remain statically typed. Canonical targets: `settings`, `oldSettings`. |

docs/ROADMAP_ARCHIVE.md

@@ -1,17 +1,17 @@
 # SplitScript roadmap
 
-## 2026-08-03: immutable per-field state normalization
+## 2026-08-03: immutable per-field state filtering
 
 - Audited AAWCB, Aragami, and the wider ASL corpus and separated three
   previously conflated behaviors. Aragami is ordinary persistent derived state
   already modeled by `whileAttached`; AAWCB requires retaining one field's
   last accepted value while other fields advance; boolean ASL `update` results
   are a later lifecycle-evaluation gate and do not roll state back.
-- Added the postfix `normalize expression` state-field clause. Its read-only
-  `value` and `previous` bindings have the field's inferred type; the first
+- Added an ordinary trailing `if` expression to state fields. Its read-only
+  `value` and `old` bindings have the field's inferred type; the first
   successful poll passes the raw candidate as both, and later polls use the
   last committed field value. `current` and `old` remain immutable and the
-  complete normalized snapshot still commits atomically.
+  complete filtered snapshot still commits atomically.
 - Added the faithful And All Would Cry Beware port. Its transient scenes 7 and
   8 are filtered without discarding entity-count changes from the same tick,
   eliminating the original mutation of `current.Scene`.