Add named state layouts and source-defined display

Author: CryZe

README.md

@@ -220,6 +220,8 @@ compile-time and output-size measurements are recorded in
   and `size` fields.
 - Compile-time checked `sig"..."` literals with byte/nibble wildcards and
   overlapping page-based module scans.
+- Checked `v"1.2.3.4"` Windows file-version literals and source-defined PE
+  resource parsing through `Module.fileVersion()`.
 - Nominal `address` values, typed synchronous/retried primitive reads,
   RIP-relative 32-bit address decoding, arbitrary-range scans, and reusable
   64-bit pointer traversal.

TODO.md

@@ -349,6 +349,15 @@ type `GbaEmulator`; scripts never retain or attach the emulator themselves.
   represented in the catalog. Begin with memory reading, formatting/
   interpolation, equality, and numeric operations; decide separately whether
   user code can declare or implement traits.
+- [x] Make nominal standard-library `Display` implementations source-driven.
+  A type declaring `Display` can tag one parameterless `String`-returning method
+  with `@display`; generated catalog metadata owns the implementation identity,
+  validates the contract, retains the ordinary hidden function through
+  reachability, and dispatches `as String`, interpolation, `print`, and
+  `setVariable` through the same body. `FileVersion.toString()` now renders the
+  dotted four-part version without any type-specific formatting branch in
+  codegen. Primitive formatting remains the built-in fallback; user-defined
+  trait implementations remain part of the broader trait design.
 - [x] Add source-defined standard-library capability inheritance. Declarations
   such as `Numeric<T: Equatable>` and `Integer<T: Numeric + Display>` now drive transitive
   satisfaction, method availability, inference, and minimal rendered bounds;
@@ -389,23 +398,33 @@ executable name.
     address global, while a single ordinary state expression reads it. Both
     supported builds and the never-ready unsupported-build path have runtime
     coverage; no layout DSL improves this shape.
-  - [ ] Separate named memory layouts from layout detection. Layout declarations
-    should co-locate concise `at` fields, documentation, and a stable source
-    identity; a distinct implicitly-suspending attachment selector should use
-    ordinary typed SplitScript expressions, `await`/`retry`, matches, process
-    metadata, module sizes, signatures, and reads to select exactly one layout.
-    Do not encode `when module(...).size == ...` as the only probe grammar.
-  - [ ] Generate a typed layout enum/value rather than exposing ASL's mutable
-    string `version`. Lifecycle code must be able to compare and exhaustively
-    match the selected layout without stringly-typed names. Decide the final
-    selector syntax together with its error policy: unsupported and ambiguous
-    builds must stay visibly unattached or fail with one useful diagnostic,
-    never silently fall back to the first declaration.
-  - [ ] Implement the first vertical slice for layouts with an identical field
-    name/type interface. Validate every layout against one canonical snapshot
-    shape and select its pointer sources before `onAttach` completes. This
-    covers roughly four fifths of the surveyed versioned scripts while keeping
-    `current.field` and `old.field` unchanged.
+  - [x] Separate named memory layouts from layout detection. `layout Name { ... }`
+    declarations co-locate concise `at` fields, documentation, and stable enum
+    variant identities. The existing implicitly-suspending `onAttach` block is
+    the selector: it uses ordinary typed SplitScript expressions, `await`/`retry`,
+    matches, process metadata, module sizes, signatures, and reads, then returns
+    exactly one generated layout variant. This keeps one attachment lifecycle
+    phase instead of adding a separate `selectLayout` action and does not encode
+    `when module(...).size == ...` as a privileged probe grammar.
+  - [x] Generate a typed `StateLayout` enum and read-only `layout` value rather
+    than exposing ASL's mutable string `version`. Lifecycle code can compare and
+    exhaustively match it. Named layouts require `onAttach` to return a variant
+    on every completing path; `await process.closed()` is recognized as the
+    explicit non-completing unsupported-build path, so there is no silent first-
+    layout fallback. `layout` is rejected inside `onAttach` before it exists.
+  - [x] Implement the first vertical slice for layouts with an identical field
+    name/type interface. Every layout is validated order-independently against
+    one canonical snapshot shape, and the selected variant dispatches each
+    transactional field read to the correct pointer source after `onAttach`
+    completes. `current.field` and `old.field` remain unchanged. Parser,
+    formatter, completion, hover, semantic highlighting, Wasm validation, and a
+    Steam/GOG/unsupported runtime fixture cover the complete feature.
+    The corpus-derived Martha Is Dead port additionally validates three real
+    legacy-ASL layouts, module-size selection, module-relative pointer paths,
+    load removal, and the unsupported-build lifecycle end to end.
+    The Borderlands port validates typed `FileVersion` selection and a shared
+    interface whose old build uses direct module offsets while its patched
+    build uses expression-backed PE32 pointer paths.
   - [ ] Design non-uniform layouts separately. The survey found 61 differing
     interfaces with stable field types and 28 with at least one same-named type
     conflict. Evaluate common-field projection plus typed variant payloads;
@@ -451,16 +470,39 @@ executable name.
   - [x] Expose `await process.mainModule()` using that matched candidate, so
     common `modules.First().ModuleMemorySize` selectors do not repeat executable
     strings or need a special module-size grammar.
-  - [ ] Add module enumeration/search, path or host-supplied file/product-version
-    identity, and a deterministic executable fingerprint as corpus ports require
-    them. Prefer host-provided metadata/fingerprinting over unrestricted
-    filesystem access or reading and hashing an entire module from Wasm.
+  - [ ] Add module enumeration/search, product-version identity, and a
+    deterministic executable fingerprint as corpus ports require them. Prefer
+    host-provided metadata/fingerprinting over unrestricted filesystem access
+    or reading and hashing an entire module from Wasm.
+    - [x] Preserve the queried module name privately in each `Module` value and
+      expose fallible `Module.path()`. It uses ASR's host-provided portable path
+      ABI, bounds the returned UTF-8 payload, and does not grant general file
+      access. Main-module values retain the actual matched process candidate;
+      named-module values retain their requested module identity.
+    - [x] Add source-defined `Module.fileVersion() -> FileVersion!` by porting
+      ASR's bounded PE-resource traversal into `standard.split`. The typed
+      `FileVersion` record exposes `major`, `minor`, `build`, and `privatePart`
+      components and is equatable, avoiding legacy `FileVersionInfo` strings
+      whose punctuation differs between games and APIs. Only typed process
+      reads remain intrinsic; DOS/PE validation, resource-directory loops,
+      `Result` propagation, and record construction are ordinary library code.
+      The checked `v"major.minor.build.private"` literal produces the same
+      typed value, validates exactly four decimal `u16` components at parse
+      time, and keeps version comparisons concise without exposing record
+      construction. The compiler lowers it through source-defined
+      `FileVersion.fromParts` rather than a second backend implementation.
 - [ ] Make the existing attach-time-discovered state-source pattern a documented
   first-class contract. Scripts can already scan/follow/resolve into globals in
   `onAttach` and use expression-backed state fields; add a canonical recipe,
   clearer typing/tooling, and specified behavior for temporarily unreadable and
   optional fields so authors do not recreate `MemoryWatcher` manually. Keep
   process-close cancellation and transactional snapshot rotation automatic.
+  The Borderlands port is a focused syntax-pressure case: its PE32 layout must
+  currently spell source-defined `MemoryPath` expressions because declarative
+  pointer paths have one implicit pointer width. Use it to decide whether
+  pointer width belongs on an individual path, a named layout, retained module
+  metadata, or a more general discovered state-source value; do not add an
+  `at32` pseudo-keyword.
 - [ ] Extend the existing signature APIs only where the corpus proves a gap:
   reusable scan targets, multiple/fallback signatures, range and memory-page
   selection, capture/offset transforms, relative-address decoding, and concise

crates/splitscript-stdlib-loader/src/generate.rs

@@ -185,11 +185,25 @@ impl<'a> CatalogGenerator<'a> {
 
     fn emit_type(&self, output: &mut String, declaration: &StructDeclaration, kind: &str) {
         let id = ident(&declaration.name);
+        let display = declaration
+            .functions
+            .iter()
+            .find(|function| has_attribute(&function.attributes, "display"))
+            .map_or_else(
+                || "None".to_owned(),
+                |function| {
+                    format!(
+                        "Some(StdlibItemId::{}{})",
+                        path_ident(&declaration.name),
+                        ident(&function.name)
+                    )
+                },
+            );
         if has_attribute(&declaration.attributes, "testOnly") {
             output.push_str("#[cfg(test)] ");
         }
         output.push_str(&format!(
-            "StdlibType {{ id: StdlibTypeId::{id}, name: {}, kind: StdlibTypeKind::{kind}, capabilities: {}, representation: {}, value_usage: {}, documentation: documentation({}, {}) }},\n",
+            "StdlibType {{ id: StdlibTypeId::{id}, name: {}, kind: StdlibTypeKind::{kind}, capabilities: {}, display: {display}, representation: {}, value_usage: {}, documentation: documentation({}, {}) }},\n",
             quote(&declaration.name), self.capabilities(&declaration.attributes),
             self.representation(&declaration.attributes), self.value_usage(&declaration.attributes),
             quote(&declaration.documentation.summary), quote(&declaration.documentation.details)
@@ -199,7 +213,7 @@ impl<'a> CatalogGenerator<'a> {
     fn emit_enum_type(&self, output: &mut String, declaration: &crate::EnumDeclaration) {
         let id = ident(&declaration.name);
         output.push_str(&format!(
-            "StdlibType {{ id: StdlibTypeId::{id}, name: {}, kind: StdlibTypeKind::Enum, capabilities: {}, representation: {}, value_usage: {}, documentation: documentation({}, {}) }},\n",
+            "StdlibType {{ id: StdlibTypeId::{id}, name: {}, kind: StdlibTypeKind::Enum, capabilities: {}, display: None, representation: {}, value_usage: {}, documentation: documentation({}, {}) }},\n",
             quote(&declaration.name), self.capabilities(&declaration.attributes),
             self.representation(&declaration.attributes), self.value_usage(&declaration.attributes),
             quote(&declaration.documentation.summary), quote(&declaration.documentation.details)
@@ -871,6 +885,50 @@ struct Duration {
         assert!(!generated.contains("IntrinsicId::DurationFromFrames"));
     }
 
+    #[test]
+    fn standard_types_can_name_a_source_defined_display_implementation() {
+        let source = r#"
+/// Displayable values.
+@behavior(declared)
+capability Display<T> {}
+
+/// Text.
+@representation(gcArray, u8, mutable, nullable)
+@valueUsage(localVariable)
+@capabilities(Display)
+intrinsic type String {}
+
+/// A file version.
+@representation(gcStruct, nullable)
+@valueUsage(localVariable)
+@capabilities(Display)
+struct FileVersion {
+    /// Major component.
+    major: u16,
+
+    /// Formats the version.
+    ///
+    /// Uses dotted components.
+    ///
+    /// # Example
+    ///
+    /// Display a version
+    ///
+    /// ```splitscript
+    /// print(version)
+    /// ```
+    @display
+    fn toString() -> String {
+        return `{self.major}`
+    }
+}
+"#;
+        let generated = generate_catalog(&parse(source).unwrap()).unwrap();
+        assert!(generated.contains("display: Some(StdlibItemId::FileVersionToString)"));
+        assert!(generated.contains("Implementation::LibraryBody"));
+        assert!(generated.contains("__splitscript_stdlib_FileVersionToString"));
+    }
+
     #[test]
     fn generic_capability_body_is_preserved_as_a_typed_template() {
         let source = r#"

crates/splitscript-stdlib-loader/src/validation.rs

@@ -221,6 +221,18 @@ impl<'a> Validator<'a> {
             attributes: value.attributes.clone(),
             functions: value.functions.clone(),
         };
+        if owner
+            .functions
+            .iter()
+            .filter(|function| has_attribute(&function.attributes, "display"))
+            .count()
+            > 1
+        {
+            self.error(format!(
+                "standard-library type `{}` has multiple display implementations",
+                owner.name
+            ));
+        }
         self.validate_functions(&owner.name, &owner.functions, &[]);
     }
 
@@ -247,7 +259,62 @@ impl<'a> Validator<'a> {
                 self.error(format!("`{owner}` repeats function `{}`", function.name));
             }
             self.validate_documentation(&qualified, &function.documentation, true);
-            self.validate_attributes(&qualified, &function.attributes, &["intrinsic"]);
+            self.validate_attributes(&qualified, &function.attributes, &["intrinsic", "display"]);
+            if has_attribute(&function.attributes, "display") {
+                if function
+                    .attributes
+                    .iter()
+                    .find(|attribute| attribute.name == "display")
+                    .is_some_and(|attribute| !attribute.arguments.is_empty())
+                {
+                    self.error(format!(
+                        "`{qualified}` marker attribute `@display` does not accept arguments"
+                    ));
+                }
+                let owner_is_standard_type = self.types.contains(owner);
+                let owner_has_display = self.library.declarations.iter().any(|declaration| {
+                    matches!(
+                        declaration,
+                        Declaration::Struct(value) | Declaration::IntrinsicType(value)
+                            if value.name == owner
+                                && value.attributes.iter().any(|attribute| {
+                                    attribute.name == "capabilities"
+                                        && attribute.arguments.iter().any(|argument| {
+                                            matches!(
+                                                argument,
+                                                AttributeArgument::Name(capability)
+                                                    if capability == "Display"
+                                            )
+                                        })
+                                })
+                    )
+                });
+                if !owner_is_standard_type {
+                    self.error(format!(
+                        "`{qualified}` uses `@display` outside a standard-library type"
+                    ));
+                }
+                if function.is_static || !function.parameters.is_empty() {
+                    self.error(format!(
+                        "`{qualified}` display implementation must be a parameterless method"
+                    ));
+                }
+                if function.result != Type::Name("String".to_owned()) {
+                    self.error(format!(
+                        "`{qualified}` display implementation must return `String`"
+                    ));
+                }
+                if !owner_has_display {
+                    self.error(format!(
+                        "`{qualified}` provides a display implementation but `{owner}` does not declare `Display`"
+                    ));
+                }
+                if function.body.is_none() {
+                    self.error(format!(
+                        "`{qualified}` display implementation must have a source body"
+                    ));
+                }
+            }
             let intrinsic = self
                 .optional_name_attribute(&qualified, &function.attributes, "intrinsic")
                 .is_some();
@@ -574,6 +641,10 @@ fn declaration_name(declaration: &Declaration) -> &str {
     }
 }
 
+fn has_attribute(attributes: &[Attribute], name: &str) -> bool {
+    attributes.iter().any(|attribute| attribute.name == name)
+}
+
 fn capability_hierarchy_has_cycle<'a>(
     capability: &'a str,
     hierarchy: &HashMap<&'a str, &'a [String]>,

crates/splitscript-syntax/src/ast.rs

@@ -253,6 +253,21 @@ pub struct Program {
 }
 
 impl Program {
+    /// Iterates both ordinary source enums and the enum generated by named
+    /// state layouts.
+    pub fn enum_declarations(&self) -> impl Iterator<Item = &EnumDecl> {
+        self.enums.iter().chain(
+            self.state
+                .as_ref()
+                .and_then(|state| state.layout_enum.as_ref()),
+        )
+    }
+
+    pub fn enum_declaration(&self, id: EnumId) -> Option<&EnumDecl> {
+        self.enum_declarations()
+            .find(|enumeration| enumeration.id == id)
+    }
+
     /// Iterates nominal type names together with their stable syntax identity
     /// and source span.
     pub fn type_names(&self) -> impl Iterator<Item = (TypeNameId, &str, Span)> {
@@ -400,6 +415,58 @@ pub struct Parameter {
 pub struct StateDecl {
     pub provider: Option<StateProviderRef>,
     pub processes: Vec<String>,
+    /// Fields of the ordinary single-layout form. This is empty when named
+    /// layouts are present.
+    pub fields: Vec<StateField>,
+    /// Versioned memory layouts. Every layout is required to expose the same
+    /// field interface by semantic analysis.
+    pub layouts: Vec<StateLayoutDecl>,
+    /// The generated enum represented by the named layout declarations.
+    pub layout_enum: Option<EnumDecl>,
+    /// Stable identity of the implicit read-only `layout` value.
+    pub layout_value: Option<ValueId>,
+    pub span: Span,
+}
+
+impl StateDecl {
+    pub fn canonical_fields(&self) -> &[StateField] {
+        self.layouts
+            .first()
+            .map_or(self.fields.as_slice(), |layout| layout.fields.as_slice())
+    }
+
+    pub fn all_fields(&self) -> impl Iterator<Item = &StateField> {
+        self.fields
+            .iter()
+            .chain(self.layouts.iter().flat_map(|layout| &layout.fields))
+    }
+
+    /// Returns the concrete read declarations in canonical field order for
+    /// each layout. This is the backend ABI between read-function planning and
+    /// per-tick dispatch.
+    pub fn ordered_read_fields(&self) -> Vec<&StateField> {
+        if self.layouts.is_empty() {
+            return self.fields.iter().collect();
+        }
+        let canonical = self.canonical_fields();
+        self.layouts
+            .iter()
+            .flat_map(|layout| {
+                canonical.iter().map(|field| {
+                    layout
+                        .fields
+                        .iter()
+                        .find(|candidate| candidate.name == field.name)
+                        .expect("checked layouts expose the canonical state interface")
+                })
+            })
+            .collect()
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct StateLayoutDecl {
+    pub variant: EnumVariantId,
     pub fields: Vec<StateField>,
     pub span: Span,
 }