Add fallible numeric string parsing

Autosplitters commonly read numeric values as native text, but ports currently need ad hoc conversion logic. Add an inferred Numeric String.parse method with exact integer range checks, strict decimal float parsing, ordinary Result semantics, editor/catalog integration, migration guidance, and a host-executed boundary regression.

Author: CryZe

TODO.md

@@ -157,8 +157,8 @@ or behavioral parity.
   async polling. A compile-only port is never labelled faithful.
 - [ ] Fill the remaining corpus-proven `String` gaps through source-defined
   APIs where possible: byte/scalar inspection consistent with the
-  language's byte-index policy, and fallible numeric parsing. ASCII case
-  conversion is complete. Improve missing-member recovery so one unknown
+  language's byte-index policy. ASCII case conversion and fallible numeric
+  parsing are complete. Improve missing-member recovery so one unknown
   method does not create unrelated unknown-local cascades.
 - [ ] Add an explicit `f32`/`f64` bit-pattern construction form and expose the
   exact rounded bits for decimal literals in tooling. Decimal exponent syntax,

crates/splitscript-syntax/src/migration.rs

@@ -449,6 +449,16 @@ pub const CONCEPTS: &[MigrationConcept] = &[
         cookbook_anchor: Some("c-string-operations"),
         spellings: STRING_ASCII_LOWER_SPELLINGS,
     },
+    MigrationConcept {
+        id: MigrationConceptId::new("string.numeric-parse"),
+        name: "Numeric string parsing",
+        sources: CSHARP,
+        support: MigrationSupport::Direct,
+        summary: "Replace static Parse/TryParse calls and output parameters with fallible `text.parse()` and ordinary Result handling.",
+        targets: &[MigrationTarget::StandardLibraryItem("String.parse")],
+        cookbook_anchor: Some("c-string-operations"),
+        spellings: &[],
+    },
     MigrationConcept {
         id: MigrationConceptId::new("type.duration"),
         name: "Timer durations",

docs/ASL_PORTING.md

@@ -105,6 +105,21 @@ The empty delimiter is an error rather than a request to split UTF-8 bytes.
 uses this mapping to parse names such as `01_02_1.dds`; its host fixture proves
 the resulting start, reset, split, and loading transitions.
 
+C# `Int32.Parse`, `Double.Parse`, and their fixed-width relatives map to
+`text.parse()`. Put the SplitScript numeric type at the receiving boundary and
+let inference flow backward:
+
+```splitscript
+let percentage: f64 = current.percentageText.parse() else 0.0
+```
+
+Unlike an exception-catching `Parse` call, failure is an ordinary `Result`.
+Use `else` for a fallback, `?` to propagate the error from a function or state
+field, or `match` when failure needs its own behavior. C# `TryParse` therefore
+does not need an output parameter. Parsing consumes the complete ASCII decimal
+string and rejects whitespace, separators, trailing text, non-finite float
+names, and values outside the chosen numeric type.
+
 ## Version-labelled ASL states
 
 The second argument in `state("game.exe", "Steam")` is a layout label, not

docs/LANGUAGE.md

@@ -1388,6 +1388,7 @@ is involved:
 | `equalsIgnoreAsciiCase(text)` | Equality folding only ASCII letters |
 | `toAsciiLowerCase()` | Lowercase ASCII letters; preserve every other UTF-8 byte |
 | `split(delimiter)` | Fallible exact split preserving leading, repeated, and trailing empty segments |
+| `parse<T>()` | Strict fallible ASCII decimal parsing into an inferred numeric type |
 | `slice(start, end)` | Fallible half-open UTF-8 byte range; offsets must be code-point boundaries |
 | `replaceAll(search, replacement)` | Fallible exact non-overlapping replacement |
 | `String.concat(values)` | Concatenate an array of strings |
@@ -1397,6 +1398,22 @@ only when at least one ASCII uppercase letter changes. It intentionally has an
 ASCII-specific name: full Unicode lowercasing can change byte length and
 requires a separate, explicitly specified API.
 
+`text.parse<T>() -> T!` parses the complete string as a numeric value. The
+target type is normally inferred from the assignment, return value, or
+fallback, and can be written explicitly when needed:
+
+```splitscript
+let percentage: f64 = current.percentageText.parse() else 0.0
+let lives = current.livesText.parse<u8>()?
+```
+
+Parsing accepts an optional ASCII sign and decimal digits. Floating-point
+targets additionally accept a decimal point and `e`/`E` exponent. Whitespace,
+digit separators, trailing text, `NaN`, and `Infinity` are rejected; integer
+overflow and target-width floating-point overflow are errors. This strictness
+keeps text read from game memory deterministic and makes malformed input use
+ordinary `Result` handling rather than silently producing a partial value.
+
 `process.readManagedString(address, maxLength)` reads a bounded IL2CPP managed
 string, decodes UTF-16 (including surrogate pairs), and returns a GC UTF-8
 `String!`. Memory-access failures are ordinary errors that can be handled with

docs/MIGRATION_CAPABILITIES.md

@@ -10,6 +10,7 @@ This index maps common source-language concepts to canonical SplitScript APIs an
 | `declaration.function` — Function declarations | C#, JavaScript | Supported directly | Functions and methods use the `fn` declaration keyword. Canonical targets: `fn`. |
 | `type.string` — String type | C# | Supported directly | The immutable UTF-8 string type is named `String`. Canonical targets: `String`. |
 | `string.ascii-lowercase` — ASCII string lowercasing | C# | Supported directly | Use `toAsciiLowerCase` when game identifiers require ASCII-only normalization; this is not culture-sensitive Unicode lowercasing. Canonical targets: `String.toAsciiLowerCase`. [Recipe](ASL_PORTING.md#c-string-operations). |
+| `string.numeric-parse` — Numeric string parsing | C# | Supported directly | Replace static Parse/TryParse calls and output parameters with fallible `text.parse()` and ordinary Result handling. Canonical targets: `String.parse`. [Recipe](ASL_PORTING.md#c-string-operations). |
 | `type.duration` — Timer durations | C# | Supported directly | Use `Duration` instead of C#'s `TimeSpan`. Canonical targets: `Duration`. |
 | `type.fixed-width-number` — Fixed-width numeric types | C# | Supported directly | Memory-facing numbers use explicit signedness and bit widths. Canonical targets: `i8`, `u8`, `i16`, `u16`, `i32`, `u32`, `i64`, `u64`, `f32`, `f64`. |
 | `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). |

docs/ROADMAP_ARCHIVE.md

@@ -2453,3 +2453,14 @@ language catalog document the refinement rule.
   The port reads the original bounded `Game.dll` level-picture field, parses
   identifiers such as `01_02_1.dds`, and proves start, reset, split, loading,
   attachment, and executable/module-name behavior.
+
+# 2026-08-09: strict fallible numeric parsing
+
+- Added `String.parse<T: Numeric>() -> T!`, with bidirectional target-type
+  inference and ordinary `Result` fallback, propagation, and matching.
+- Integer parsing is exact across every signed and unsigned width (including
+  `address`); floating-point parsing supports decimal points and exponents and
+  rejects non-finite names and target-width overflow.
+- Added compiler/editor catalog coverage, ASL/C# migration guidance, and a
+  host-executed regression for boundaries, malformed input, inference,
+  floating-point syntax, overflow, and underflow.

src/bin/xtask.rs

@@ -464,6 +464,13 @@ const RUNTIME_FIXTURES: &[RuntimeFixture] = &[
         harness: "tests/string_predicates_runtime.mjs",
         extra_arguments: &[],
     },
+    RuntimeFixture {
+        source: "tests/string_parsing.split",
+        output: "string_parsing.wasm",
+        profile: "release",
+        harness: "tests/string_parsing_runtime.mjs",
+        extra_arguments: &[],
+    },
     RuntimeFixture {
         source: "examples/tiberian_sun.split",
         output: "tiberian_sun.wasm",

src/codegen/expression.rs

@@ -2166,6 +2166,65 @@ fn compile_expr_unconverted(
                     context,
                 );
             }
+            IntrinsicId::StringParse => {
+                let Type::Result(result) = ty else {
+                    unreachable!("String.parse produces a Result value")
+                };
+                let parsed_type = result_value_type(result, context.semantics);
+                compile_receiver(function, target, context);
+                match parsed_type {
+                    Type::I8
+                    | Type::U8
+                    | Type::I16
+                    | Type::U16
+                    | Type::I32
+                    | Type::U32
+                    | Type::I64
+                    | Type::U64
+                    | Type::Address => {
+                        let (allow_negative, positive_limit, negative_limit) =
+                            integer_parse_limits(parsed_type);
+                        function
+                            .instruction(&Instruction::I32Const(i32::from(allow_negative)))
+                            .instruction(&Instruction::I64Const(positive_limit))
+                            .instruction(&Instruction::I64Const(negative_limit))
+                            .instruction(&Instruction::Call(
+                                context
+                                    .runtime_helpers
+                                    .function(RuntimeHelperId::StringParseInteger),
+                            ));
+                        if matches!(
+                            parsed_type,
+                            Type::I8 | Type::U8 | Type::I16 | Type::U16 | Type::I32 | Type::U32
+                        ) {
+                            function.instruction(&Instruction::I32WrapI64);
+                            emit_narrow_i32(function, parsed_type);
+                        }
+                    }
+                    Type::F32 | Type::F64 => {
+                        function
+                            .instruction(&Instruction::I32Const(i32::from(
+                                parsed_type == Type::F32,
+                            )))
+                            .instruction(&Instruction::Call(
+                                context
+                                    .runtime_helpers
+                                    .function(RuntimeHelperId::StringParseFloat),
+                            ));
+                        if parsed_type == Type::F32 {
+                            function.instruction(&Instruction::F32DemoteF64);
+                        }
+                    }
+                    _ => unreachable!("Numeric parsing requires a concrete numeric type"),
+                }
+                emit_status_result(
+                    function,
+                    expression,
+                    parsed_type,
+                    "string is not valid decimal text for the inferred numeric type",
+                    context,
+                );
+            }
             IntrinsicId::StringSlice => {
                 compile_receiver(function, target, context);
                 compile_expr(function, args[0], context);
@@ -2851,6 +2910,47 @@ fn emit_sentinel_result(
     function.instruction(&Instruction::End);
 }
 
+/// Converts a helper's `(success, value)` multi-value result into `T!`. The
+/// value is stored first, leaving the success flag on the operand stack.
+fn emit_status_result(
+    function: &mut Function,
+    expression: ExprId,
+    value_type: Type,
+    message: &str,
+    context: &ExprContext<'_>,
+) {
+    let Type::Result(result) = context.expression_type(expression) else {
+        unreachable!("status-bearing helpers produce Result values")
+    };
+    let value_local = context.matches.intrinsic_temps[&expression][0];
+    function
+        .instruction(&Instruction::LocalSet(value_local))
+        .instruction(&Instruction::I32Eqz)
+        .instruction(&Instruction::If(BlockType::Result(
+            context.gc.val_type(Type::Result(result)),
+        )));
+    emit_result_error(function, result, value_type, message, context.gc);
+    function
+        .instruction(&Instruction::Else)
+        .instruction(&Instruction::LocalGet(value_local));
+    emit_result_success(function, result, context.gc);
+    function.instruction(&Instruction::End);
+}
+
+fn integer_parse_limits(ty: Type) -> (bool, i64, i64) {
+    match ty {
+        Type::I8 => (true, i8::MAX as i64, 1_i64 << 7),
+        Type::U8 => (false, u8::MAX as i64, u8::MAX as i64),
+        Type::I16 => (true, i16::MAX as i64, 1_i64 << 15),
+        Type::U16 => (false, u16::MAX as i64, u16::MAX as i64),
+        Type::I32 => (true, i32::MAX as i64, 1_i64 << 31),
+        Type::U32 => (false, u32::MAX as i64, u32::MAX as i64),
+        Type::I64 => (true, i64::MAX, i64::MIN),
+        Type::U64 | Type::Address => (false, -1, -1),
+        _ => unreachable!("integer parse limits require an integer type"),
+    }
+}
+
 fn emit_cast(function: &mut Function, expression: ExprId, target: Type, context: &ExprContext<'_>) {
     let source = context.expression_type(expression);
     compile_expr(function, expression, context);

src/codegen/runtime_helper_registry.rs

@@ -41,6 +41,7 @@ impl RuntimeHelperPlan {
 pub(super) enum HelperValueType {
     I32,
     I64,
+    F64,
     String,
     Standard(StdlibTypeId),
     StringArray,
@@ -80,7 +81,7 @@ macro_rules! helper {
     };
 }
 
-use HelperValueType::{I32, I64, I64Array, Standard, String as StringValue, StringArray};
+use HelperValueType::{F64, I32, I64, I64Array, Standard, String as StringValue, StringArray};
 
 /// Canonical function-index and body order. Dependencies always occur before
 /// the helpers that call them, which is validated by the registry tests.
@@ -94,6 +95,8 @@ pub(super) const DESCRIPTORS: &[RuntimeHelperDescriptor] = &[
     helper!(StringToAsciiLowerCase, (StringValue) -> (StringValue), deps [], imports [], build_string_to_ascii_lower_case),
     helper!(StringReplaceAll, (StringValue, StringValue, StringValue) -> (StringValue), deps [StringFind], imports [], build_string_replace_all),
     helper!(StringSplit, (StringValue, StringValue) -> (StringArray), deps [StringFind], imports [], build_string_split),
+    helper!(StringParseInteger, (StringValue, I32, I64, I64) -> (I32, I64), deps [], imports [], build_string_parse_integer),
+    helper!(StringParseFloat, (StringValue, I32) -> (I32, F64), deps [], imports [], build_string_parse_float),
     helper!(StringSlice, (StringValue, I32, I32) -> (StringValue), deps [], imports [], build_string_slice),
     helper!(ScanProcessRange, (I64, I64, I64, I32, I32, I32) -> (I64), deps [], imports [ProcessRead], build_scan_process_range),
     helper!(ReadRelative32, (I64, I64) -> (I64), deps [], imports [ProcessRead], build_read_relative32),
@@ -216,6 +219,7 @@ pub(super) fn resolve_signature(
     let resolve = |ty| match ty {
         HelperValueType::I32 => ValType::I32,
         HelperValueType::I64 => ValType::I64,
+        HelperValueType::F64 => ValType::F64,
         HelperValueType::String => gc.val_type(Type::Standard(StdlibTypeId::String)),
         HelperValueType::Standard(standard) => gc.val_type(Type::Standard(standard)),
         HelperValueType::StringArray | HelperValueType::I64Array => gc.val_type(Type::Array(
@@ -255,6 +259,7 @@ fn required_array_layout(
         HelperValueType::I64Array => Type::I64,
         HelperValueType::I32
         | HelperValueType::I64
+        | HelperValueType::F64
         | HelperValueType::String
         | HelperValueType::Standard(_) => return None,
     };

src/codegen/runtime_helpers.rs

@@ -101,6 +101,14 @@ pub(super) fn build_string_split(inputs: &RuntimeHelperInputs<'_>) -> Function {
     )
 }
 
+pub(super) fn build_string_parse_integer(inputs: &RuntimeHelperInputs<'_>) -> Function {
+    strings::compile_string_parse_integer(inputs.gc)
+}
+
+pub(super) fn build_string_parse_float(inputs: &RuntimeHelperInputs<'_>) -> Function {
+    strings::compile_string_parse_float(inputs.gc)
+}
+
 pub(super) fn build_string_slice(inputs: &RuntimeHelperInputs<'_>) -> Function {
     strings::compile_string_slice(inputs.gc)
 }