standard.split

/// Attaches to one of the native processes named by the state declaration.
///
/// Each candidate is an exact host process identity. The current Windows host
/// reports executable filenames including `.exe`, so Windows candidates must
/// include that extension. Use an array for alternate executable names; the
/// provider tries them in order and attaches to one matching process.
///
/// The read-only value has type [`Process`] and is a handle to the attached game
/// process.
///
/// # Example
///
/// Read native process memory
///
/// ```splitscript
/// state "game.exe" {}
/// whileAttached {
///     let health = process.read<i32>(0x1234) else 0
/// }
/// ```
///
/// # Example
///
/// Try alternate executable names
///
/// ```splitscript
/// state ["game.exe", "game-demo.exe"] {}
/// onAttach {
///     print(process.name())
/// }
/// ```
@processType(Process)
@processes(source)
@default
@attachment(identity)
@directRead(ProcessRead)
stateProvider Native as process {}

/// Attaches to a Unity game and binds declared managed metadata schemas.
///
/// Automatic mode waits for either an IL2CPP `GameAssembly.dll` runtime or a
/// modern `mono-2.0-bdwgc.dll` runtime. It derives the supported metadata
/// layout from the loaded Unity player rather than guessing from schema names.
/// Use an explicit selector only when the target's exact metadata family is
/// known and automatic detection is inappropriate.
///
/// The read-only process value remains a native [`Process`] handle. Managed
/// images and classes declared with [`image`] are the public managed-memory
/// interface. Their reachable metadata is bound once before [`onAttach`] runs;
/// scripts do not discover runtime images, classes, field offsets, or static
/// tables themselves. The attachment-scoped [`unity`](provider@Unity) value
/// separately exposes native scene and hierarchy facilities.
///
/// A declared class name such as `PlayerController` is an immutable local
/// snapshot type. `PlayerController.Ref` is a live remote reference. Following
/// a live static or instance field is fallible and rereads replaceable object
/// pointers on every state poll. Calling `.snapshot()` reads all active fields
/// transactionally. Scalar live reads allocate no GC objects; snapshots,
/// strings, arrays, and instance-search results materialize owned values.
/// Generated binders, readers, and runtime discovery are retained only when
/// reachable from the script.
///
/// # Example
///
/// Detect the Unity backend automatically
///
/// ```splitscript
/// state Unity ["game.exe"] {}
/// ```
///
/// # Example
///
/// Read one transactional managed snapshot
///
/// ```splitscript
/// image "Assembly-CSharp" {
///     class GameManager {
///         static GameManager instance;
///         u32 score;
///         bool finished;
///     }
/// }
///
/// state Unity ["game.exe"] {
///     manager: GameManager = GameManager.instance?.snapshot()?;
/// }
/// ```
///
/// # Example
///
/// Read a managed component from the active scene hierarchy
///
/// ```splitscript
/// state Unity ["game.exe"] {
///     player = unity.scenes.active()?
///         .find("World/Player")?
///         .component<PlayerController>()?
///         .snapshot();
/// }
///
/// image "Assembly-CSharp" {
///     class PlayerController {
///         u32 score;
///     }
/// }
/// ```
@processType(Process)
@processes(source)
@attachment(identity)
@prepare(UnityProviderAuto)
@directRead(ProcessRead)
stateProvider Unity as process {
    /// Provides attachment-scoped Unity engine facilities.
    ///
    /// The value is available wherever the attached [`process`] is available.
    /// Its members are discovered once before user [`onAttach`] code runs.
    ///
    /// # Example
    ///
    /// Track the active native Unity scene
    ///
    /// ```splitscript
    /// state Unity ["game.exe"] {
    ///     scene = unity.scenes.active();
    /// }
    /// ```
    @prepare(UnityProviderContext)
    context unity: UnityContext,

    /// Selects a known IL2CPP metadata layout.
    ///
    /// This bypasses Unity-version detection while retaining cooperative
    /// GameAssembly and metadata discovery.
    @prepare(UnityProviderIl2Cpp)
    @managedBackend(il2cpp)
    selector il2cpp(version: u32),

    /// Selects a known modern Mono metadata layout.
    ///
    /// This bypasses Unity-version detection while retaining cooperative Mono
    /// module and metadata discovery.
    @prepare(UnityProviderMono)
    @managedBackend(mono)
    selector mono(version: MonoVersion),
}

/// Attaches to a supported Game Boy Advance emulator.
///
/// The provider discovers emulated EWRAM and IWRAM and exposes original GBA
/// hardware addresses through the read-only value introduced by [`GBA`].
/// It owns discovery for VisualBoyAdvance and VBA-M, mGBA, NO$GBA, Mednafen,
/// supported RetroArch cores, and mGBA-based BizHawk. Declare guest addresses
/// directly instead of recreating emulator-specific `DeepPointer` mappings.
///
/// # Example
///
/// Read GBA work RAM
///
/// ```splitscript
/// state GBA {
///     room: u8 at 0x03000010
/// }
/// ```
@processType(GBAEmulator)
@attachment(GBAEmulatorDiscover)
@validate(GBAEmulatorMappingIsAvailable)
@directRead(GBAEmulatorRead)
stateProvider GBA as gba {
    "visualboyadvance-m.exe",
    "VisualBoyAdvance.exe",
    "mGBA.exe",
    "mGBA",
    "NO$GBA.EXE",
    "retroarch.exe",
    "EmuHawk.exe",
    "mednafen.exe",
}

/// Attaches to a supported PlayStation 2 emulator.
///
/// The provider discovers the emulator's main RAM mapping and exposes original
/// PS2 addresses through the read-only `ps2` value of type [`PS2Emulator`].
/// PCSX2 and 64-bit RetroArch using `pcsx2_libretro.dll` are supported.
/// Declare guest addresses directly instead of recreating emulator-specific
/// `DeepPointer` mappings.
///
/// # Example
///
/// Read PS2 memory
///
/// ```splitscript
/// state PS2 {
///     health: u16 at 0x00123456
/// }
/// ```
@processType(PS2Emulator)
@attachment(PS2EmulatorDiscover)
@validate(PS2EmulatorMappingIsAvailable)
@directRead(PS2EmulatorRead)
@readableRange(0x00100000, 0x02000000)
stateProvider PS2 as ps2 {
    "pcsx2x64.exe",
    "pcsx2-qt.exe",
    "pcsx2x64-avx2.exe",
    "pcsx2-avx2.exe",
    "pcsx2.exe",
    "retroarch.exe",
}

/// Attaches to a supported PlayStation emulator.
///
/// The provider discovers emulated main RAM and exposes original PlayStation
/// addresses through the read-only `ps1` value of type [`PS1Emulator`].
/// It owns discovery for ePSXe, pSX, DuckStation, Mednafen, PCSX-Redux, XEBRA,
/// and supported RetroArch cores. Declare guest addresses directly instead of
/// recreating emulator-specific `DeepPointer` mappings.
///
/// # Example
///
/// Read PlayStation memory
///
/// ```splitscript
/// state PS1 {
///     health: u16 at 0x80012346
/// }
/// ```
@processType(PS1Emulator)
@attachment(PS1EmulatorDiscover)
@validate(PS1EmulatorMappingIsAvailable)
@directRead(PS1EmulatorRead)
stateProvider PS1 as ps1 {
    "ePSXe.exe",
    "psxfin.exe",
    "duckstation-qt-x64-ReleaseLTCG.exe",
    "duckstation-nogui-x64-ReleaseLTCG.exe",
    "retroarch.exe",
    "pcsx-redux.main",
    "XEBRA.EXE",
    "mednafen.exe",
}

/// Attaches to a supported Sega Master System or Game Gear emulator.
///
/// The provider exposes original 16-bit console addresses through the read-only
/// `sms` value of type [`SMSEmulator`].
/// It owns discovery for Fusion, BlastEm, Mednafen, and supported RetroArch
/// cores. Declare guest addresses directly instead of recreating
/// emulator-specific `DeepPointer` mappings.
///
/// # Example
///
/// Read Master System work RAM
///
/// ```splitscript
/// state SMS {
///     lives: u8 at 0xc010
/// }
/// ```
@processType(SMSEmulator)
@attachment(SMSEmulatorDiscover)
@validate(SMSEmulatorMappingIsAvailable)
@directRead(SMSEmulatorRead)
stateProvider SMS as sms {
    "retroarch.exe",
    "Fusion.exe",
    "blastem.exe",
    "mednafen.exe",
}

/// Attaches to a supported Sega Genesis emulator.
///
/// The provider discovers the console's 64 KiB work RAM and exposes original
/// Genesis offsets through the read-only `genesis` value of type
/// [`GenesisEmulator`]. It normalizes the word-swapped storage used by several
/// emulators before decoding values in the console's big-endian byte order.
/// It owns discovery for Fusion, Gens, BlastEm, Sega Game Room, Sega Genesis
/// Classics, and supported RetroArch cores. Declare guest offsets directly
/// instead of recreating emulator-specific `DeepPointer` mappings or manual
/// byte-order correction.
///
/// # Example
///
/// Read Genesis work RAM
///
/// ```splitscript
/// state Genesis {
///     score: u32 at 0x1200
/// }
/// ```
@processType(GenesisEmulator)
@attachment(GenesisEmulatorDiscover)
@validate(GenesisEmulatorMappingIsAvailable)
@directRead(GenesisEmulatorRead)
stateProvider Genesis as genesis {
    "retroarch.exe",
    "SEGAGameRoom.exe",
    "SEGAGenesisClassics.exe",
    "Fusion.exe",
    "gens.exe",
    "blastem.exe",
}

/// Attaches to a supported Nintendo GameCube emulator.
///
/// The provider discovers the console's 24 MiB MEM1 mapping and exposes
/// original GameCube addresses through the read-only `gcn` value of type
/// [`GCNEmulator`]. Multi-byte values are decoded using the console's
/// big-endian byte order.
/// It owns discovery for Dolphin and 64-bit RetroArch using
/// `dolphin_libretro.dll`. Declare guest addresses directly instead of
/// recreating Dolphin mappings, `DeepPointer` chains, or byte swapping.
///
/// # Example
///
/// Read GameCube memory
///
/// ```splitscript
/// state GCN {
///     room: u16 at 0x80001000
/// }
/// ```
@processType(GCNEmulator)
@attachment(GCNEmulatorDiscover)
@validate(GCNEmulatorMappingIsAvailable)
@directRead(GCNEmulatorRead)
stateProvider GCN as gcn {
    "Dolphin.exe",
    "retroarch.exe",
}

/// Attaches to a supported Nintendo Wii emulator.
///
/// The provider discovers MEM1 and MEM2 and exposes original Wii addresses
/// through the read-only `wii` value of type [`WiiEmulator`]. Multi-byte
/// values use the console's big-endian byte order.
/// It owns discovery for Dolphin and 64-bit RetroArch using
/// `dolphin_libretro.dll`. Declare MEM1 or MEM2 guest addresses directly
/// instead of recreating Dolphin mappings, `DeepPointer` chains, or byte
/// swapping.
///
/// # Example
///
/// Read Wii memory
///
/// ```splitscript
/// state Wii {
///     room: u16 at 0x80001000
/// }
/// ```
@processType(WiiEmulator)
@attachment(WiiEmulatorDiscover)
@validate(WiiEmulatorMappingIsAvailable)
@directRead(WiiEmulatorRead)
stateProvider Wii as wii {
    "Dolphin.exe",
    "retroarch.exe",
}

root {
    private fn dolphinCoreBase() -> async address {
        if process.name() != "retroarch.exe" {
            return 0
        }

        let executable = await process.mainModule()
        if retry executable.pointerSize() != PointerSize.Bit64 {
            await process.closed()
        }
        let core = await process.module("dolphin_libretro.dll")
        return core.address
    }

    /// Prints a diagnostic message.
    ///
    /// The message is forwarded to the autosplitting runtime.
    ///
    /// # Example
    ///
    /// Write to the runtime log
    ///
    /// ```splitscript
    /// print(42)
    /// ```
    @intrinsic(Print)
    fn print<T: Display>(
        /// The value to write to the runtime log.
        message: T,
    ) -> None;

    /// Sets a custom variable in the timer runtime.
    ///
    /// The value is visible to layouts that display autosplitter variables.
    ///
    /// # Example
    ///
    /// Expose a layout variable
    ///
    /// ```splitscript
    /// setVariable("Points", 42)
    /// ```
    @intrinsic(TimerSetVariable)
    fn setVariable<T: Display>(
        /// The variable name.
        name: String,
        /// The displayed value. It is converted to text using the same rules
        /// as string interpolation.
        value: T,
    ) -> None;

    /// Changes the autosplitter tick rate.
    ///
    /// The value is a frequency in updates per second. SplitScript normally
    /// applies 120 Hz immediately after attaching, before [`onAttach`], and 1
    /// Hz during module startup and immediately after detaching, before
    /// [`onDetach`]. A top-level [`tickRate`] declaration changes those
    /// lifecycle-owned defaults.
    ///
    /// This function instead changes the wait after the current update. Its
    /// rate persists until another call or the next attachment transition,
    /// when the corresponding declarative rate is reapplied. Use it only for a
    /// genuinely temporary dynamic adjustment.
    ///
    /// # Example
    ///
    /// Temporarily reduce polling during module discovery
    ///
    /// ```splitscript
    /// setTickRate(30)
    /// let assets = await process.module("assets.dll")
    /// setTickRate(120)
    /// print(`Assets loaded at {assets.address}`)
    /// ```
    @intrinsic(RuntimeSetTickRate)
    fn setTickRate<T: Numeric>(
        /// The positive, finite number of requested updates per second.
        hz: T,
    ) -> None;

    /// Continues attachment on the next runtime update.
    ///
    /// Always suspends once. The continuation resumes on the following attached-process tick and is cancelled if that process closes first.
    ///
    /// # Example
    ///
    /// Resume on the next update
    ///
    /// ```splitscript
    /// await nextTick()
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(NextTick)
    fn nextTick() -> async None;
}

/// Coordinates lazy asynchronous values without exposing threads or background tasks.
///
/// Future combinators only make progress when their returned future is polled with
/// [`await`]. They preserve the attachment-lifetime cancellation of their inputs.
///
/// # Example
///
/// Coordinate alternative asynchronous work
///
/// ```splitscript
/// # state "game.exe" {}
/// # onAttach {
/// await future.race([nextTick(), nextTick()])
/// print("one tick operation completed")
/// # }
/// ```
namespace future {
    /// Waits for the first operation that completes.
    ///
    /// Calling this function only captures the array. Polling the returned future
    /// polls the operations in array order on each runtime update, and the first
    /// ready value wins. When several operations become ready during the same
    /// update, the lowest array index wins. An empty array remains pending forever.
    /// After completion, this combinator stops polling the other operations; an
    /// operation retained elsewhere remains available through that shared handle.
    ///
    /// # Example
    ///
    /// Race alternate module names
    ///
    /// ```splitscript
    /// # state ["game.exe", "game-demo.exe"] {}
    /// # onAttach {
    /// let executable = await future.race([
    ///     process.module("game.exe"),
    ///     process.module("game-demo.exe"),
    /// ])
    /// # print(executable.address)
    /// # }
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(FutureRace)
    fn race<T>(
        /// Lazy operations with the same completion type.
        operations: [async T],
    ) -> async T;

    /// Waits for an operation until a duration has elapsed.
    ///
    /// Calling this function is lazy: the deadline starts when the returned
    /// future is first polled. Each runtime update polls `operation` before
    /// checking the monotonic deadline, so a value that becomes ready exactly
    /// at the deadline wins. A zero or negative duration permits one immediate
    /// poll and then fails if the operation is still pending.
    ///
    /// A timeout uses the ordinary [`T!`] error channel. If `operation` already
    /// completes with a fallible value, its error and the timeout share that
    /// single channel. The error text is intended for display, not for
    /// programmatic classification. Once this wrapper times out, it no longer
    /// polls `operation`; a future handle stored elsewhere remains valid and
    /// may still be awaited independently.
    ///
    /// # Example
    ///
    /// Bound module discovery
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// # onAttach {
    /// let executable = await future.timeout(
    ///     process.module("game.exe"),
    ///     Duration.fromSeconds(5),
    /// ) else {
    ///     print("the game module was not discovered in time")
    ///     await process.closed()
    /// }
    /// # print(executable.address)
    /// # }
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(FutureTimeout)
    fn timeout<T>(
        /// The lazy operation to poll.
        operation: async T,
        /// The maximum time for which the operation may remain pending.
        duration: Duration,
    ) -> async T!;
}

/// Reads metadata about the autosplitting runtime host.
///
/// These values describe the system running the autosplitting runtime, not necessarily the
/// architecture of the attached game process.
///
/// # Example
///
/// Inspect the host platform
///
/// ```splitscript
/// let hostOs = runtime.operatingSystem() else "unknown"
/// let hostArchitecture = runtime.architecture() else "unknown"
/// print(`Running on {hostOs} ({hostArchitecture})`)
/// ```
namespace runtime {
    /// Returns the runtime host's operating-system name.
    ///
    /// Common values are `windows`, `linux`, and `macos`. The result remains a
    /// string so new host operating systems do not require a language update.
    ///
    /// # Example
    ///
    /// Select platform-specific metadata handling
    ///
    /// ```splitscript
    /// let hostOs = runtime.operatingSystem() else "unknown"
    /// ```
    @intrinsic(RuntimeOperatingSystem)
    fn operatingSystem() -> String!;

    /// Returns the runtime host's architecture name.
    ///
    /// Common values include `x86`, `x86_64`, `arm`, and `aarch64`. This is the
    /// runtime architecture rather than a guarantee about the attached process.
    ///
    /// # Example
    ///
    /// Report the host architecture
    ///
    /// ```splitscript
    /// let hostArchitecture = runtime.architecture() else "unknown"
    /// ```
    @intrinsic(RuntimeArchitecture)
    fn architecture() -> String!;
}

/// Selects either the current or previous values of the script's declared settings.
///
/// The compiler supplies [`settings`] and [`oldSettings`]; copying either value is
/// allocation-free because the value only identifies one of the two snapshots.
///
/// # Example
///
/// Look up a boolean setting by its stable host key
///
/// ```splitscript
/// # state "game.exe" {}
/// # settings { "Split boss" => splitBoss key "split-boss": true }
/// # whileAttached {
/// if settings.enabled("split-boss") {
///     print("Boss splitting is enabled")
/// }
/// # }
/// ```
@representation(scalar, i32)
@valueUsage(localVariable, globalVariable)
intrinsic type SettingsView {
    /// Returns a declared boolean setting selected by its stable host-map key.
    ///
    /// String literals are checked against the declared boolean keys and are
    /// completed by editor tooling. When a declaration has a statically visible
    /// source name, a literal lookup is warned and can be rewritten directly to
    /// `settings.name` or `oldSettings.name`. Computed unknown keys, and computed
    /// keys belonging to non-boolean settings, return false. The lookup reads
    /// the already-refreshed settings snapshot and does not query the host or
    /// allocate.
    ///
    /// # Example
    ///
    /// Select a data-driven split
    ///
    /// ```splitscript
    /// let missionKey = "42"
    /// let shouldSplit = settings.enabled(missionKey)
    /// ```
    @intrinsic(SettingsEnabled)
    fn enabled(
        /// The exact string key declared with `key "..."`, or the setting's
        /// source identifier when it has no explicit key.
        key: String,
    ) -> bool;

    /// Reports whether a value setting declares the stable host key.
    ///
    /// This distinguishes a known disabled boolean from an unknown key.
    /// Literal keys are checked and completed against boolean, choice, and
    /// file declarations. A literal naming a declared value is always true and
    /// is warned with a semantics-preserving rewrite; use a typed member to read
    /// that setting's value instead. Computed strings may still be unknown at
    /// runtime. Headings are visual structure rather than values and are not
    /// included.
    ///
    /// # Example
    ///
    /// Advance a data cursor even when its known split is disabled
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// # onAttach {
    /// # let checkpointKey = "checkpoint"
    /// # let checkpointIndex = 0
    /// if settings.contains(checkpointKey) {
    ///     checkpointIndex += 1
    /// }
    /// # }
    /// ```
    @intrinsic(SettingsContains)
    fn contains(
        /// The exact stable host-map key.
        key: String,
    ) -> bool;
}

/// Accesses the attached game process.
///
/// Process operations discover modules, read memory, follow pointers, and scan signatures.
/// Inside [`selectProcess`], this same value refers to the temporary same-name
/// candidate being inspected. Returning `true` promotes that candidate;
/// returning `false` or propagating an error detaches it before provider setup.
///
/// # Example
///
/// Read the matched process identity
///
/// ```splitscript
/// let executableName = process.name()
/// ```
@representation(scalar, i64)
@valueUsage(localVariable, globalVariable)
@capabilities(MemoryReader)
intrinsic type Process {
    /// Native addresses are represented by the language's wide address value.
    type Address = address;

    /// Returns the configured process name that matched during attachment.
    ///
    /// This is the exact candidate written in the state declaration, not a
    /// filesystem path. It lets attachment discovery distinguish executable
    /// variants without granting file access. Same-name candidates therefore
    /// have the same value; use [`Process.path`] or another stable probe inside
    /// [`selectProcess`] when they must be distinguished.
    ///
    /// # Example
    ///
    /// Distinguish executable variants
    ///
    /// ```splitscript
    /// let executable = process.name()
    /// ```
    @requires(attachedProcess)
    @intrinsic(ProcessName)
    fn name() -> String;

    /// Returns the executable's host-provided filesystem path.
    ///
    /// The returned value is an absolute path in the runtime's portable,
    /// read-only filesystem namespace. Windows paths map by drive, so
    /// `C:\Games\game.exe` becomes `/mnt/c/Games/game.exe`. Linux and macOS
    /// paths gain the `/mnt` prefix, so `/opt/game/game` becomes
    /// `/mnt/opt/game/game`. It can be passed directly to [`File.readAllBytes`]
    /// or [`File.readAllText`]. The path is also available while inspecting a
    /// candidate in [`selectProcess`].
    ///
    /// # Example
    ///
    /// Inspect the attached executable path
    ///
    /// ```splitscript
    /// let executablePath = process.path() else "Unavailable"
    /// ```
    @requires(attachedProcess)
    @intrinsic(ProcessPath)
    fn path() -> String!;

    /// Waits for the main executable module.
    ///
    /// The module name comes from the exact process candidate that matched
    /// during attachment. This is useful for version probes based on the main
    /// module's address or mapped size without repeating executable names.
    ///
    /// # Example
    ///
    /// Inspect the main module
    ///
    /// ```splitscript
    /// let executable = await process.mainModule()
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(ProcessMainModule)
    fn mainModule() -> async Module;

    /// Ignores the current attachment until the process closes.
    ///
    /// This suspension never closes or detaches the process itself and never
    /// completes normally. When the process closes, the automatic process
    /// lifetime boundary cancels the surrounding [`onAttach`] or
    /// [`whileAttached`] invocation before it can resume.
    ///
    /// # Example
    ///
    /// Ignore an unsupported build
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// # onAttach {
    /// # let unsupported = true
    /// if unsupported {
    ///     await process.closed()
    /// }
    /// # }
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(ProcessClosed)
    fn closed() -> async Never;

    /// Waits for a process module.
    ///
    /// Suspends the surrounding attachment lifecycle invocation until both
    /// module address and size are available.
    ///
    /// # Example
    ///
    /// Wait for a module
    ///
    /// ```splitscript
    /// let gameAssembly = await process.module("GameAssembly.dll")
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(ProcessModule)
    fn module(
        /// The exact module name.
        @literal(string)
        name: String,
    ) -> async Module;

    /// Returns a module only when it is already loaded.
    ///
    /// Unlike [`module`], this probe is synchronous and does not wait for a
    /// missing optional module to appear. It is useful for selecting layouts
    /// that depend on optional platform or mod-loader modules.
    ///
    /// # Example
    ///
    /// Detect an optional Steam module
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// # onAttach {
    /// let steam = process.loadedModule("steam_api.dll") else return
    /// # print(steam.address)
    /// # }
    /// ```
    @mustUse("the optional loaded module is otherwise discarded")
    @requires(attachedProcess)
    @intrinsic(ProcessLoadedModule)
    fn loadedModule(
        /// The exact module name.
        name: String,
    ) -> Module?;

    /// Searches mapped memory ranges cooperatively.
    ///
    /// A bounded batch of host memory-range metadata is inspected per update.
    /// This does not read the contents of those ranges. When one complete
    /// snapshot contains no match, the operation refreshes the mapped ranges
    /// and keeps waiting. It completes only after finding the requested size
    /// and permissions; closing the attached process cancels it.
    ///
    /// # Example
    ///
    /// Find a readable and writable emulator mapping
    ///
    /// ```splitscript
    /// let mapping = await process.findMemoryRange(0x48000, MemoryRangeAccess.ReadWrite)
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(ProcessFindMemoryRange)
    fn findMemoryRange(
        /// The exact mapped byte length.
        size: u64,
        /// Permissions that the range must provide.
        access: MemoryRangeAccess,
    ) -> async MemoryRange;

    /// Collects a snapshot of the process's mapped memory ranges.
    ///
    /// The returned GC-owned snapshot is ordered by the host's range index and
    /// remains usable after later host mapping changes.
    ///
    /// # Example
    ///
    /// Inspect readable executable mappings
    ///
    /// ```splitscript
    /// let ranges = process.memoryRanges()
    /// for range in ranges {
    ///     if range.readable && range.executable {
    ///         debug print(`executable mapping at {range.address}`)
    ///     }
    /// }
    /// ```
    @mustUse("the collected memory-range snapshot is otherwise discarded")
    @requires(attachedProcess)
    @intrinsic(ProcessMemoryRanges)
    fn memoryRanges() -> [MemoryRange];

    /// Reads a fixed-layout value from process memory.
    ///
    /// The expected [`MemoryReadable`] type selects a fixed-size primitive,
    /// integer-represented [`enum`], [`struct`], or fixed-array layout. A
    /// synchronous read returns [`T!`]; [`retry`] polls until a value is
    /// available and yields `T`. Use an explicit type argument such as
    /// `process.read<i32>` when context cannot determine the type. Unknown enum
    /// discriminants fail the complete read.
    ///
    /// # Example
    ///
    /// Read a typed value
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// # onAttach {
    /// # let player: address = 0x1000
    /// let health = process.read<i32>(player.offset(0x20)) else 0
    /// # print(health)
    /// # }
    /// ```
    ///
    /// # Example
    ///
    /// Infer the memory layout from an expected type
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// # onAttach {
    /// # let player: address = 0x1000
    /// let level: u32 = process.read(player.offset(0x24)) else 0
    /// # print(level)
    /// # }
    /// ```
    @requires(attachedProcess)
    @intrinsic(ProcessRead)
    fn read<T: MemoryReadable>(
        /// The target address to read.
        address: address,
    ) -> T!;

    /// Follows a pointer path.
    ///
    /// Each signed offset is applied with wrapping address arithmetic before
    /// reading the next pointer at the attached executable's automatically
    /// detected native width. A failed or null pointer read returns an error;
    /// use retry in onAttach to wait for success.
    ///
    /// # Example
    ///
    /// Follow a pointer path
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// # onAttach {
    /// # let module = await process.mainModule()
    /// let player = retry process.follow(module.address, [0x100, 0x20])
    /// # print(player)
    /// # }
    /// ```
    @requires(attachedProcess)
    @intrinsic(ProcessFollow)
    fn follow(
        /// The initial address.
        base: address,
        /// Signed pointer offsets to follow.
        offsets: [i64],
    ) -> address!;

    /// Scans a process-memory range.
    ///
    /// Suspends until the signature is found in the requested range. Large
    /// ranges are scanned cooperatively across ticks so the autosplitter keeps
    /// yielding to the host.
    ///
    /// # Example
    ///
    /// Scan a memory range
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// # onAttach {
    /// # let module = await process.mainModule()
    /// let marker = await process.scan(module.address, module.size, sig"48 8B ?? 89")
    /// # print(marker)
    /// # }
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(ProcessScan)
    fn scan(
        /// The beginning of the range.
        address: address,
        /// The number of bytes to scan.
        size: u64,
        /// The compiled signature pattern.
        signature: Signature,
    ) -> async address;

    /// Scans one complete pass over a process-memory range.
    ///
    /// Unlike [`Process.scan`], this operation does not begin another pass when
    /// the signature is absent. It returns [`Some`] with the first matching
    /// address, or [`None`] after the entire requested range has been exhausted.
    /// The pass remains cooperative across ticks, skips windows that cannot be
    /// read, and is cancelled automatically when the process closes.
    ///
    /// Use this when absence is meaningful, such as rejecting an unsupported
    /// executable. Use [`Process.scan`] when the signature may appear later and
    /// the operation should keep waiting.
    ///
    /// # Example
    ///
    /// Reject an executable without the expected marker
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// # onAttach {
    /// # let module = await process.mainModule()
    /// let marker = await process.scanOnce(
    ///     module.address,
    ///     module.size,
    ///     sig"48 8B ?? 89",
    /// )
    /// match marker {
    ///     Some(address) => print(`marker at {address}`),
    ///     None => print("unsupported executable"),
    /// }
    /// # }
    /// ```
    @mustUse("The finite scan result is otherwise discarded.")
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(ProcessScanOnce)
    fn scanOnce(
        /// The beginning of the range.
        address: address,
        /// The number of bytes to scan.
        size: u64,
        /// The compiled signature pattern.
        signature: Signature,
    ) -> async address?;

    /// Scans every readable mapped memory range in the process.
    ///
    /// Ranges are visited from the highest address to the lowest address and
    /// unreadable mappings are skipped. The operation suspends until a match
    /// exists and is cancelled automatically when the process closes. Prefer
    /// module or explicit-range scans when the target is known because they
    /// perform less work. Only a bounded window is inspected per tick, so even
    /// a large process-wide search keeps yielding to the host.
    ///
    /// This can initialize an attachment-scoped address in [`onAttach`] or
    /// rediscover an allocation that moved while the same process remains
    /// open from [`whileAttached`]. A pending per-update invocation suppresses
    /// timer decisions until the scan completes.
    ///
    /// # Example
    ///
    /// Discover a runtime-created marker outside known modules
    ///
    /// ```splitscript
    /// let timerData = await process.scanMemory(sig"54 49 4D 52 ?? ?? ?? ??")
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(ProcessScanMemory)
    fn scanMemory(
        /// The compiled signature pattern.
        signature: Signature,
    ) -> async address;

    /// Scans for the first of several signatures across process memory.
    ///
    /// Signatures are tried in array order within each bounded memory window.
    /// The returned index identifies the matching array element. The operation
    /// remains cooperative and is cancelled when the process closes.
    ///
    /// # Example
    ///
    /// Discover one of several supported layouts
    ///
    /// ```splitscript
    /// let found = await process.scanMemoryAny([
    ///     sig"48 8B 05 ?? ?? ?? ??",
    ///     sig"48 8B 1D ?? ?? ?? ??",
    /// ])
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(ProcessScanMemoryAny)
    fn scanMemoryAny(
        /// Candidate patterns in priority order. The array must not be empty.
        signatures: [Signature],
    ) -> async SignatureMatch;

    /// Resolves a 32-bit relative address.
    ///
    /// Reads a signed displacement and adds it to the address following the displacement. A failed or null target returns an error; use retry in onAttach to wait for success.
    ///
    /// # Example
    ///
    /// Resolve a relative target
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// # onAttach {
    /// # let instruction: address = 0x1000
    /// let target = retry process.readRelative32(instruction.offset(3))
    /// # print(target)
    /// # }
    /// ```
    @requires(attachedProcess)
    @intrinsic(ProcessReadRelative32)
    fn readRelative32(
        /// The address of a signed relative displacement.
        address: address,
    ) -> address!;
}

/// Reads information from the timer.
///
/// Timer operations expose runtime state used by autosplitter decisions.
///
/// # Example
///
/// Inspect the timer through its namespace
///
/// ```splitscript
/// let currentTimerState = timer.state()
/// ```
namespace timer {
    /// Returns the current timer state.
    ///
    /// Host states are converted to NotRunning, Running, Paused, Ended, or Unknown at the ABI boundary.
    ///
    /// # Example
    ///
    /// Check whether the timer is running
    ///
    /// ```splitscript
    /// let isRunning = timer.state() == TimerState.Running
    /// ```
    @intrinsic(TimerState)
    fn state() -> TimerState;

    /// Returns the index of the split the current attempt is on.
    ///
    /// [`None`] means that no attempt is in progress. The signed host ABI uses a
    /// negative value for that state; all nonnegative values are exposed as
    /// [`u64`]. The index equals the segment count after the final split. An
    /// increased index means that the timer advanced, including through a skip.
    /// If an undo and another split both happen between updates, the unchanged
    /// index cannot reveal that sequence; an exact timer-event API would require
    /// additional host support.
    ///
    /// # Example
    ///
    /// Observe timer advancement
    ///
    /// ```splitscript
    /// let splitIndex = timer.currentSplitIndex() else return
    /// ```
    @intrinsic(TimerCurrentSplitIndex)
    fn currentSplitIndex() -> u64?;

    /// Reports how an earlier segment was advanced during this attempt.
    ///
    /// Returns [`Some`]`(true)` when the segment was split, [`Some`]`(false)`
    /// when it was skipped, and [`None`] when the index has not been reached in the
    /// current attempt. This is historical attempt data; the current and later
    /// segment indices therefore return [`None`].
    ///
    /// # Example
    ///
    /// Check whether the first segment was split
    ///
    /// ```splitscript
    /// let firstSegmentWasSplit = timer.segmentWasSplit(0)
    /// ```
    @intrinsic(TimerSegmentWasSplit)
    fn segmentWasSplit(
        /// Zero-based segment index.
        index: u64,
    ) -> bool?;

    /// Skips the current split.
    ///
    /// This directly advances the timer without recording the current segment
    /// as split. Use it only when the autosplitter intentionally controls timer
    /// history rather than merely deciding whether its [`split`] block fires.
    ///
    /// # Example
    ///
    /// Skip a segment that does not exist in this route
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// # onAttach {
    /// # let routeOmitsCurrentSegment = true
    /// if routeOmitsCurrentSegment {
    ///     timer.skipSplit()
    /// }
    /// # }
    /// ```
    @intrinsic(TimerSkipSplit)
    fn skipSplit() -> None;

    /// Undoes the previous split.
    ///
    /// The timer moves back one segment when its current state permits it.
    /// This is an explicit timer mutation and is separate from autosplitter
    /// snapshot history.
    ///
    /// # Example
    ///
    /// Correct an automatically detected false positive
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// # onAttach {
    /// # let falsePositiveDetected = true
    /// if falsePositiveDetected {
    ///     timer.undoSplit()
    /// }
    /// # }
    /// ```
    @intrinsic(TimerUndoSplit)
    fn undoSplit() -> None;

    /// Pauses the timer's game-time clock.
    ///
    /// [`isLoading`] should remain the normal way to remove loads. This explicit
    /// operation is intended for lifecycle transitions such as ensuring game
    /// time does not advance after the attached process closes.
    ///
    /// # Example
    ///
    /// Pause game time after detaching
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// onDetach {
    ///     timer.pauseGameTime()
    /// }
    /// ```
    @intrinsic(TimerPauseGameTime)
    fn pauseGameTime() -> None;

    /// Resumes the timer's game-time clock.
    ///
    /// Prefer returning `false` from [`isLoading`] for ordinary load removal.
    /// Use this operation only when lifecycle logic explicitly paused game
    /// time outside that action.
    ///
    /// # Example
    ///
    /// Resume game time after attaching
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// onAttach {
    ///     timer.resumeGameTime()
    /// }
    /// ```
    @intrinsic(TimerResumeGameTime)
    fn resumeGameTime() -> None;

    /// Reports whether the timer is currently running.
    ///
    /// This is a convenience check over the exhaustive timer state.
    ///
    /// # Example
    ///
    /// Check whether a run is active
    ///
    /// ```splitscript
    /// if timer.isRunning() {
    ///     print("The timer is running")
    /// }
    /// ```
    fn isRunning() -> bool {
        return timer.state() == TimerState.Running
    }
}

/// Provides Unity runtime utilities outside managed schema declarations.
///
/// Use the [`Unity`] state provider with top-level [`image`] and [`class`]
/// declarations for managed Mono or IL2CPP state. This namespace contains
/// supplementary Unity facilities such as native scene discovery; raw managed
/// metadata traversal is an implementation detail of the provider.
///
/// # Example
///
/// Read the active native Unity scene
///
/// ```splitscript
/// # state Unity ["game.exe"] {}
/// onAttach {
///     let active = unity.scenes.active() else return
///     print(active.name)
/// }
/// ```
namespace Unity {
    // Builds the provider's backend-independent context after auto-detection.
    private fn providerAuto() -> async UnityRuntime {
        loop {
            let il2cppLoaded = match process.loadedModule("GameAssembly.dll") {
                Some(_) => true,
                None => false,
            }
            if il2cppLoaded {
                let version = await Unity.detectIl2cppVersion()
                return await Unity.providerIl2cpp(version)
            }

            let monoLoaded = match process.loadedModule("mono-2.0-bdwgc.dll") {
                Some(_) => true,
                None => false,
            }
            if monoLoaded {
                let version = await Unity.detectMonoVersion()
                return await Unity.providerMono(version)
            }

            await nextTick()
        }
    }

    // Builds an IL2CPP provider context with an explicitly selected layout.
    private fn providerIl2cpp(version: u32) -> async UnityRuntime {
        let runtime = await Unity.il2cpp(version)
        return UnityRuntime {
            backend: UnityRuntimeBackend.Il2cpp,
            il2cpp: Some(runtime),
            mono: None,
        }
    }

    // Builds a Mono provider context with an explicitly selected layout.
    private fn providerMono(version: MonoVersion) -> async UnityRuntime {
        let runtime = await Unity.mono(version)
        return UnityRuntime {
            backend: UnityRuntimeBackend.Mono,
            il2cpp: None,
            mono: Some(runtime),
        }
    }

    // Constructs the public attachment-scoped Unity facilities. This is
    // emitted only when the provider context is referenced by user code.
    private fn providerContext() -> async UnityContext {
        return UnityContext {
            scenes: await Unity.sceneManager(),
        }
    }

    // Mirrors ASR's supported Windows IL2CPP layout detection.
    private fn detectIl2cppVersion() -> async u32 {
        let player = await process.module("UnityPlayer.dll")
        let pointerSize = retry player.pointerSize()
        if pointerSize == PointerSize.Bit32 {
            return 0
        }

        let version = retry player.fileVersion()
        if version.major > 2022
            || version.major == 2022 && version.minor >= 2
        {
            return 2022
        }
        if version.major == 2021
            || version.major == 2020 && version.minor >= 2
        {
            return 2020
        }
        if version.major == 2019 || version.major == 2020 {
            return 2019
        }
        return 0
    }

    // Mirrors ASR's modern Windows Mono V2/V3 layout detection.
    private fn detectMonoVersion() -> async MonoVersion {
        let player = await process.module("UnityPlayer.dll")
        let version = retry player.fileVersion()
        if version.major > 2021
            || version.major == 2021 && version.minor >= 2
        {
            return MonoVersion.V3
        }
        return MonoVersion.V2
    }

    // Discovers the IL2CPP metadata used by the generated Unity schema binder.
    private fn il2cpp(
        // The Unity metadata layout version.
        version: u32,
    ) -> async UnityModule {
        if version != 0 && version != 2019 && version != 2020 && version != 2022 {
            await process.closed()
        }

        let gameAssembly = await process.module("GameAssembly.dll")
        let assembliesInstruction = await gameAssembly.scan(sig"75 ?? 48 8B 1D ?? ?? ?? ?? 48 3B 1D")
        let assemblies = retry process.readRelative32(assembliesInstruction.offset(5))
        let metadata = await gameAssembly.scan(sig"67 6C 6F 62 61 6C 2D 6D 65 74 61 64 61 74 61 2E 64 61 74 00")

        let metadataInstruction = await gameAssembly.scanRelative32Target(sig"48 8D 0D", 3, metadata)
        let metadataReference = metadataInstruction.offset(3)

        let shiftInstruction = await process.scan(
            metadataReference,
            0x200,
            sig"48 C1 E9",
        )
        let storeInstruction = await process.scan(
            shiftInstruction.offset(3),
            0x100,
            sig"48 89 05",
        )
        let typeInformation = retry process.readRelative32(storeInstruction.offset(3))

        return UnityModule {
            assemblies,
            typeInfoTable: typeInformation,
            version,
            pointerSize: 8,
        }
    }

    // Discovers the Mono metadata used by the generated Unity schema binder.
    private fn mono(
        // Exact Mono metadata layout used by the target Unity release.
        version: MonoVersion,
    ) -> async MonoModule {
        return await MonoModule.discover(version)
    }

    // Discovers Unity's native scene manager for the provider context.
    private fn sceneManager() -> async UnityScenes {
        let unityPlayer = retry {
            process.loadedModule("UnityPlayer.dll")
                else process.loadedModule("UnityPlayer.so")
                else process.loadedModule("UnityPlayer.dylib")
                else throw "UnityPlayer is not loaded yet"
        }

        let isPortableExecutable = retry process.read<u16>(unityPlayer.address) == 0x5a4d
        let pointerSize = if isPortableExecutable {
            retry unityPlayer.pointerSize()
        } else {
            PointerSize.Bit64
        }

        let managerPointer = match pointerSize {
            PointerSize.Bit64 => {
                let signature = if isPortableExecutable {
                    sig"48 83 EC 20 4C 8B ?5 ?? ?? ?? ?? 33 F6"
                } else {
                    sig"41 54 53 50 4C 8B ?5 ?? ?? ?? ?? 41 83"
                }
                let instruction = await unityPlayer.scan(signature)
                retry process.readRelative32(instruction.add(7))
            },
            PointerSize.Bit32 => {
                let found = await unityPlayer.scanAny([
                    sig"55 8B EC 51 A1 ?? ?? ?? ?? 53 33 DB",
                    sig"53 8D 41 ?? 33 DB",
                    sig"55 8B EC 83 EC 18 A1 ?? ?? ?? ?? 33 C9 53",
                ])
                match found.index {
                    0 => retry process.read<u32>(found.address.add(5)) as address,
                    1 => retry process.read<u32>(found.address.offset(-4)) as address,
                    _ => retry process.read<u32>(found.address.add(7)) as address,
                }
            },
        }

        let managerAddress: address = retry {
            let address: address = match pointerSize {
                PointerSize.Bit32 => process.read<u32>(managerPointer)? as address,
                PointerSize.Bit64 => process.read<u64>(managerPointer)? as address,
            }
            if address == 0 {
                throw "Unity scene manager is not initialized yet"
            }
            address
        }

        return UnityScenes {
            address: managerAddress,
            pointerSize,
        }
    }
}

/// Internal backend tag retained by the provider preparation context.
///
/// Generated schema binders dispatch through this tag while the public schema
/// surface remains independent from Mono and IL2CPP metadata representations.
///
/// # Example
///
/// Select a concrete managed backend through the public provider
///
/// ```splitscript
/// state Unity.il2cpp(2020) ["game.exe"] {}
/// ```
@representation(enum, nullable)
@valueUsage(structField, localVariable)
private enum UnityRuntimeBackend {
    /// Selects the IL2CPP metadata adapter.
    ///
    /// The associated context contains a discovered [`UnityModule`].
    ///
    /// # Example
    ///
    /// Select the IL2CPP 2019 layout
    ///
    /// ```splitscript
    /// state Unity.il2cpp(2019) ["game.exe"] {}
    /// ```
    Il2cpp,

    /// Selects the Mono metadata adapter.
    ///
    /// The associated context contains a discovered [`MonoModule`].
    ///
    /// # Example
    ///
    /// Select the modern Mono V3 layout
    ///
    /// ```splitscript
    /// state Unity.mono(MonoVersion.V3) ["game.exe"] {}
    /// ```
    Mono,
}

/// Internal backend-independent context consumed by generated schema binders.
///
/// Exactly one backend payload is present. Keeping both representations behind
/// one private struct lets schema lowering share one attachment lifecycle.
///
/// # Example
///
/// Create the context through automatic provider discovery
///
/// ```splitscript
/// state Unity ["unity-game.exe"] {}
/// ```
@representation(gcStruct, nullable)
@valueUsage(localVariable)
private struct UnityRuntime {
    /// Identifies the populated backend payload.
    ///
    /// Generated binders use this tag for exhaustive adapter dispatch.
    private backend: UnityRuntimeBackend,

    /// Contains the IL2CPP runtime when that backend was selected.
    ///
    /// Mono contexts leave this value absent.
    private il2cpp: UnityModule?,

    /// Contains the Mono runtime when that backend was selected.
    ///
    /// IL2CPP contexts leave this value absent.
    private mono: MonoModule?,

    // Returns the native pointer width through the backend-neutral schema
    // adapter used by compiler-generated metadata binding.
    private fn pointerBytes() -> u32 {
        return match self.backend {
            UnityRuntimeBackend.Il2cpp => {
                let runtime = self.il2cpp else return 0
                runtime.pointerSize
            },
            UnityRuntimeBackend.Mono => {
                let runtime = self.mono else return 0
                match runtime.pointerSize {
                    PointerSize.Bit32 => 4,
                    PointerSize.Bit64 => 8,
                }
            },
        }
    }

    // Finds an image without exposing which managed backend owns it.
    private fn image(name: String) -> async UnityMetadataImage {
        return match self.backend {
            UnityRuntimeBackend.Il2cpp => {
                let runtime = self.il2cpp else await process.closed()
                UnityMetadataImage {
                    backend: self.backend,
                    il2cpp: await runtime.image(name),
                    mono: None,
                }
            },
            UnityRuntimeBackend.Mono => {
                let runtime = self.mono else await process.closed()
                UnityMetadataImage {
                    backend: self.backend,
                    il2cpp: None,
                    mono: await runtime.image(name),
                }
            },
        }
    }
}

/// Backend-neutral image used only by generated Unity schema binding.
///
/// # Example
///
/// Bind a source image through automatic Unity discovery
///
/// ```splitscript
/// image "Assembly-CSharp" {
///     class GameManager {}
/// }
/// state Unity ["game.exe"] {}
/// ```
@representation(gcStruct, nullable)
@valueUsage(localVariable)
private struct UnityMetadataImage {
    /// Identifies the populated backend image.
    private backend: UnityRuntimeBackend,

    /// Contains the image when the runtime uses IL2CPP.
    private il2cpp: UnityImage?,

    /// Contains the image when the runtime uses Mono.
    private mono: MonoImage?,

    // Finds exactly one source-declared class through the selected backend.
    private fn classAny(names: [String]) -> async UnityMetadataClass {
        return match self.backend {
            UnityRuntimeBackend.Il2cpp => {
                let image = self.il2cpp else await process.closed()
                UnityMetadataClass {
                    backend: self.backend,
                    il2cpp: await image.classAny(names),
                    mono: None,
                }
            },
            UnityRuntimeBackend.Mono => {
                let image = self.mono else await process.closed()
                UnityMetadataClass {
                    backend: self.backend,
                    il2cpp: None,
                    mono: await image.classAny(names),
                }
            },
        }
    }
}

/// Backend-neutral class used only by generated Unity schema binding.
///
/// # Example
///
/// Bind a source class through automatic Unity discovery
///
/// ```splitscript
/// image "Assembly-CSharp" {
///     class Player {}
/// }
/// state Unity ["game.exe"] {}
/// ```
@representation(gcStruct, nullable)
@valueUsage(localVariable)
private struct UnityMetadataClass {
    /// Identifies the populated backend class.
    private backend: UnityRuntimeBackend,

    /// Contains the class when the runtime uses IL2CPP.
    private il2cpp: UnityClass?,

    /// Contains the class when the runtime uses Mono.
    private mono: MonoClass?,

    // Resolves one required source field through the selected backend.
    private fn fieldAny(names: [String]) -> async UnityField {
        return match self.backend {
            UnityRuntimeBackend.Il2cpp => {
                let class = self.il2cpp else await process.closed()
                await class.fieldAny(names)
            },
            UnityRuntimeBackend.Mono => {
                let class = self.mono else await process.closed()
                await class.fieldAny(names)
            },
        }
    }

    // Probes one conditional source field through the selected backend.
    private fn probeFieldAny(names: [String]) -> async UnityField? {
        return match self.backend {
            UnityRuntimeBackend.Il2cpp => {
                let class = self.il2cpp else await process.closed()
                await class.probeFieldAny(names)
            },
            UnityRuntimeBackend.Mono => {
                let class = self.mono else await process.closed()
                await class.probeFieldAny(names)
            },
        }
    }

    // Resolves the complete address of a required static field. The backend
    // uses the runtime class that actually declares an inherited field rather
    // than assuming that its storage belongs to the schema class.
    private fn staticFieldAny(names: [String]) -> async address {
        return match self.backend {
            UnityRuntimeBackend.Il2cpp => {
                let class = self.il2cpp else await process.closed()
                await class.staticFieldAny(names)
            },
            UnityRuntimeBackend.Mono => {
                let class = self.mono else await process.closed()
                await class.staticFieldAny(names)
            },
        }
    }

    // Preserves completed absence for conditional schema fields.
    private fn probeStaticFieldAny(names: [String]) -> async address? {
        return match self.backend {
            UnityRuntimeBackend.Il2cpp => {
                let class = self.il2cpp else await process.closed()
                await class.probeStaticFieldAny(names)
            },
            UnityRuntimeBackend.Mono => {
                let class = self.mono else await process.closed()
                await class.probeStaticFieldAny(names)
            },
        }
    }

    // Finds the selected class's static storage through either backend.
    private fn staticTable() -> async address {
        return match self.backend {
            UnityRuntimeBackend.Il2cpp => {
                let class = self.il2cpp else await process.closed()
                await class.staticTable()
            },
            UnityRuntimeBackend.Mono => {
                let class = self.mono else await process.closed()
                await class.staticTable()
            },
        }
    }

    // Returns the object-header pointer used to identify live instances of
    // this class while scanning process memory.
    private fn instanceHeader() -> async address {
        return match self.backend {
            UnityRuntimeBackend.Il2cpp => {
                let class = self.il2cpp else await process.closed()
                class.instanceHeader()
            },
            UnityRuntimeBackend.Mono => {
                let class = self.mono else await process.closed()
                await class.instanceHeader()
            },
        }
    }
}

/// Supports ordered numeric operations.
///
/// Numeric values provide minimum, maximum, clamping, ordered comparisons, and
/// equality while preserving their inferred type. Integer arithmetic results
/// wrap to the declared integer width.
///
/// # Example
///
/// Keep an integer below a limit
///
/// ```splitscript
/// let cappedStage = 12.min(7)
/// ```
@behavior(declared)
capability Numeric: Equatable {
    /// Adds another value of the same numeric type.
    ///
    /// This method is also the implementation of the
    /// [`+`](operator@Numeric.add) operator. Integer
    /// overflow wraps modulo the receiver's declared bit width.
    ///
    /// # Example
    ///
    /// Add two values
    ///
    /// ```splitscript
    /// let total = 20 + 22
    /// ```
    @intrinsic(NumericAdd)
    @operator(add)
    fn add(
        /// The value to add.
        other: Self,
    ) -> Self;

    /// Subtracts another value of the same numeric type.
    ///
    /// This method is also the implementation of the
    /// [`-`](operator@Numeric.subtract) operator. Integer
    /// overflow wraps modulo the receiver's declared bit width.
    ///
    /// # Example
    ///
    /// Subtract two values
    ///
    /// ```splitscript
    /// let difference = 50 - 8
    /// ```
    @intrinsic(NumericSubtract)
    @operator(subtract)
    fn subtract(
        /// The value to subtract.
        other: Self,
    ) -> Self;

    /// Multiplies by another value of the same numeric type.
    ///
    /// This method is also the implementation of the
    /// [`*`](operator@Numeric.multiply) operator. Integer
    /// overflow wraps modulo the receiver's declared bit width.
    ///
    /// # Example
    ///
    /// Convert a page count to bytes
    ///
    /// ```splitscript
    /// let byteCount = 12u32 * 4096
    /// ```
    @intrinsic(NumericMultiply)
    @operator(multiply)
    fn multiply(
        /// The value to multiply by.
        other: Self,
    ) -> Self;

    /// Divides by another value of the same numeric type.
    ///
    /// This method is also the implementation of the
    /// [`/`](operator@Numeric.divide) operator. Integer
    /// division truncates toward zero. Integer division by zero and the signed
    /// minimum divided by negative one trap, matching WebAssembly arithmetic;
    /// floating-point division follows IEEE 754.
    ///
    /// # Example
    ///
    /// Convert milliseconds to seconds
    ///
    /// ```splitscript
    /// let elapsedSeconds = 15_000u64 / 1_000
    /// ```
    @intrinsic(NumericDivide)
    @operator(divide)
    fn divide(
        /// The divisor.
        other: Self,
    ) -> Self;

    /// Multiplies this value by itself.
    ///
    /// Integer multiplication wraps to the receiver's declared width.
    /// Floating-point multiplication rounds at the receiver's f32 or f64
    /// width and follows IEEE 754 for zero, infinity, and NaN.
    ///
    /// # Example
    ///
    /// Square a coordinate delta
    ///
    /// ```splitscript
    /// let squaredDistance = 3.5.squared()
    /// ```
    fn squared() -> Self {
        return self * self
    }

    /// Returns the smaller of two numeric values.
    ///
    /// Both values have the same inferred numeric type and are evaluated once.
    /// For floating-point values, either NaN input produces NaN. If the values
    /// are positive and negative zero, negative zero is returned.
    ///
    /// # Example
    ///
    /// Keep the smaller value
    ///
    /// ```splitscript
    /// let visibleStage = 9u32.min(7)
    /// ```
    @intrinsic(NumericMin)
    fn min(
        /// The other value to compare with the receiver.
        other: Self,
    ) -> Self;

    /// Returns the larger of two numeric values.
    ///
    /// Both values have the same inferred numeric type and are evaluated once.
    /// For floating-point values, either NaN input produces NaN. If the values
    /// are positive and negative zero, positive zero is returned.
    ///
    /// # Example
    ///
    /// Keep the larger value
    ///
    /// ```splitscript
    /// let nonNegativeScore = (-4).max(0)
    /// ```
    @intrinsic(NumericMax)
    fn max(
        /// The other value to compare with the receiver.
        other: Self,
    ) -> Self;

    /// Restricts a numeric value to an inclusive range.
    ///
    /// The receiver and bounds have one inferred numeric type and are evaluated once.
    ///
    /// # Example
    ///
    /// Restrict a value to a range
    ///
    /// ```splitscript
    /// let visibleStage = 9u32.clamp(1, 7)
    /// ```
    fn clamp(
        /// The inclusive lower bound.
        minimum: Self,
        /// The inclusive upper bound.
        maximum: Self,
    ) -> Self {
        let lowerBounded = self.max(minimum)
        return lowerBounded.min(maximum)
    }

    /// Reverses the order of the bytes in this numeric value.
    ///
    /// The result keeps the receiver's exact type and raw bit pattern.
    /// Eight-bit integers are unchanged because they contain only one byte.
    /// Floating-point values reverse their IEEE 754 representation and then
    /// reinterpret those bits as the same floating-point type; this is not a
    /// numeric conversion. The method is useful when a value was read using
    /// the opposite byte order, such as big-endian process memory decoded by
    /// [`Process.read`].
    ///
    /// # Example
    ///
    /// Decode a big-endian integer
    ///
    /// ```splitscript
    /// let decoded = 0x3412u16.swapBytes()
    /// ```
    @mustUse("Byte swapping returns a new value and does not modify its receiver.")
    @intrinsic(NumericSwapBytes)
    fn swapBytes() -> Self;
}

/// Identifies integral numeric types.
///
/// Integer operations and inference constraints accept only whole-number
/// representations. Every integer is also numeric and displayable.
///
/// # Example
///
/// Preserve an exact integer width
///
/// ```splitscript
/// let inventoryMask: u8 = 1 << 2
/// ```
@behavior(declared)
capability Integer: Numeric + Display {
    /// Formats this integer using a positional numeral system.
    ///
    /// Radices from 2 through 36 are supported. Digits above nine use
    /// lowercase ASCII letters. Signed values keep a leading minus sign and
    /// format their mathematical magnitude, including the minimum value of a
    /// signed integer type. Use [`toAsciiUpperCase`] on the result when uppercase
    /// digits are desired. An unsupported radix returns an error.
    ///
    /// # Example
    ///
    /// Format a hexadecimal identifier
    ///
    /// ```splitscript
    /// let cellId = 0x00abcdefu32
    /// let hexadecimal = cellId.toString(16) else ""
    /// ```
    @mustUse("Integer radix formatting returns a new string and does not modify its receiver.")
    @intrinsic(IntegerToStringRadix)
    fn toString(
        /// The numeral-system radix, from 2 through 36 inclusive.
        radix: u32,
    ) -> String!;

    /// Returns the width-preserving bitwise complement of this integer.
    ///
    /// This method is also the integer implementation of the
    /// [`!`](operator@Integer.bitNot) operator.
    /// Every bit in the receiver's declared integer representation is flipped;
    /// for example, complementing a [`u8`] never affects bits outside that byte.
    /// Boolean [`!`] remains logical negation and is selected by type.
    ///
    /// # Example
    ///
    /// Invert an eight-bit mask
    ///
    /// ```splitscript
    /// let inverse: u8 = !0x0fu8
    /// ```
    @intrinsic(IntegerBitNot)
    @operator(not)
    fn bitNot() -> Self;

    /// Returns the remainder after integer division.
    ///
    /// This method is also the implementation of the
    /// [`%`](operator@Integer.remainder) operator. The result
    /// has the same sign as the receiver. A zero divisor traps, matching
    /// WebAssembly integer arithmetic.
    ///
    /// # Example
    ///
    /// Test a frame interval
    ///
    /// ```splitscript
    /// let isInterval = 120u32 % 60 == 0
    /// ```
    @intrinsic(IntegerRemainder)
    @operator(remainder)
    fn remainder(
        /// The divisor.
        other: Self,
    ) -> Self;

    /// Combines two integers with a bitwise OR.
    ///
    /// This method is also the implementation of the
    /// [`|`](operator@Integer.bitOr) operator.
    ///
    /// # Example
    ///
    /// Add a flag to a mask
    ///
    /// ```splitscript
    /// let combined = 0x10u32 | 0x20
    /// ```
    @intrinsic(IntegerBitOr)
    @operator(bitOr)
    fn bitOr(
        /// The other integer.
        other: Self,
    ) -> Self;

    /// Combines two integers with a bitwise exclusive OR.
    ///
    /// This method is also the implementation of the
    /// [`^`](operator@Integer.bitXor) operator.
    ///
    /// # Example
    ///
    /// Toggle a flag in a mask
    ///
    /// ```splitscript
    /// let toggled = 0x30u32 ^ 0x20
    /// ```
    @intrinsic(IntegerBitXor)
    @operator(bitXor)
    fn bitXor(
        /// The other integer.
        other: Self,
    ) -> Self;

    /// Combines two integers with a bitwise AND.
    ///
    /// This method is also the implementation of the
    /// [`&`](operator@Integer.bitAnd) operator.
    ///
    /// # Example
    ///
    /// Isolate one flag from a mask
    ///
    /// ```splitscript
    /// let selected = 0x30u32 & 0x20
    /// ```
    @intrinsic(IntegerBitAnd)
    @operator(bitAnd)
    fn bitAnd(
        /// The other integer.
        other: Self,
    ) -> Self;

    /// Shifts bits to the left.
    ///
    /// This method is also the implementation of the
    /// [`<<`](operator@Integer.shiftLeft) operator. Only the
    /// low five bits of the shift count are used for values represented as
    /// i32, including 8- and 16-bit integers; i64, u64, and address values use
    /// the low six bits. Bits shifted out of the representation are discarded.
    ///
    /// # Example
    ///
    /// Construct a bit mask
    ///
    /// ```splitscript
    /// let mask = 1u32 << 5
    /// ```
    @intrinsic(IntegerShiftLeft)
    @operator(shiftLeft)
    fn shiftLeft(
        /// The shift count, inferred as the receiver's integer type.
        count: Self,
    ) -> Self;

    /// Shifts bits to the right.
    ///
    /// This method is also the implementation of the
    /// [`>>`](operator@Integer.shiftRight) operator. Signed
    /// values copy the sign bit; unsigned and address values shift in zeroes.
    /// Shift counts use the same low-five or low-six-bit rule as [`shiftLeft`].
    ///
    /// # Example
    ///
    /// Extract a packed byte
    ///
    /// ```splitscript
    /// let highByte = 0x1234u32 >> 8
    /// ```
    @intrinsic(IntegerShiftRight)
    @operator(shiftRight)
    fn shiftRight(
        /// The shift count, inferred as the receiver's integer type.
        count: Self,
    ) -> Self;
}

/// Identifies signed numeric types.
///
/// Signed values can represent numbers below zero and support all numeric
/// operations.
///
/// # Example
///
/// Store a signed delta
///
/// ```splitscript
/// let levelDelta: i32 = -4
/// ```
@behavior(declared)
capability Signed: Numeric {
    /// Returns this value with its sign inverted.
    ///
    /// This method is also the implementation of unary
    /// [`-`](operator@Signed.negate). Integer minimum
    /// values wrap to themselves, matching WebAssembly integer subtraction;
    /// floating-point values toggle their sign bit, including zero and NaN.
    ///
    /// # Example
    ///
    /// Invert a signed offset
    ///
    /// ```splitscript
    /// let reverseOffset = -20i32
    /// ```
    @intrinsic(SignedNegate)
    @operator(negate)
    fn negate() -> Self;

    /// Returns this value without a negative sign.
    ///
    /// Floating-point negative zero becomes positive zero and NaN remains NaN.
    /// Signed-integer arithmetic follows the language's wrapping rule, so the
    /// minimum value of an integer type remains itself because its positive
    /// counterpart is not representable in that type.
    ///
    /// # Example
    ///
    /// Measure the magnitude of a signed delta
    ///
    /// ```splitscript
    /// let distance = (-12i32).abs()
    /// ```
    fn abs() -> Self {
        return self.max(-self)
    }
}

/// Identifies floating-point types.
///
/// Floating-point constraints accept f32 and f64 values and imply signed
/// numeric behavior together with [`Debug`] and [`Display`]. Their default
/// text is the shortest correctly rounded decimal that parses back to the
/// original value. Signed zero remains visible, and non-finite values use
/// `NaN`, `inf`, and `-inf`.
///
/// # Example
///
/// Round a floating-point value
///
/// ```splitscript
/// let nearest = 2.5.round()
/// let text = nearest as String
/// ```
@behavior(declared)
capability Float: Signed + Debug {
    /// Returns the principal square root of this value.
    ///
    /// Positive finite values produce a non-negative result. Positive infinity
    /// remains infinity, signed zero preserves its sign, and a negative value
    /// other than negative zero produces NaN. Existing NaN values remain NaN.
    ///
    /// # Example
    ///
    /// Measure a two-dimensional distance
    ///
    /// ```splitscript
    /// let distance = (3.0 * 3.0 + 4.0 * 4.0).sqrt()
    /// ```
    @intrinsic(FloatSqrt)
    fn sqrt() -> Self;

    /// Rounds this value toward zero to an integral value.
    ///
    /// Positive fractions round down and negative fractions round up. Signed
    /// zero preserves its sign. Infinity and NaN are returned unchanged.
    ///
    /// # Example
    ///
    /// Remove the fractional part of a measured time
    ///
    /// ```splitscript
    /// let wholeSeconds = 12.75.truncate()
    /// ```
    @intrinsic(FloatTruncate)
    fn truncate() -> Self;

    /// Rounds down to the nearest integral value.
    ///
    /// Finite fractional values move toward negative infinity. Infinity and
    /// NaN are returned unchanged.
    ///
    /// # Example
    ///
    /// Round a timer down
    ///
    /// ```splitscript
    /// let wholeSeconds = 12.75.floor()
    /// ```
    @intrinsic(FloatFloor)
    fn floor() -> Self;

    /// Rounds up to the nearest integral value.
    ///
    /// Finite fractional values move toward positive infinity. Infinity and
    /// NaN are returned unchanged.
    ///
    /// # Example
    ///
    /// Round a counter up
    ///
    /// ```splitscript
    /// let requiredPages = 2.25.ceil()
    /// ```
    @intrinsic(FloatCeil)
    fn ceil() -> Self;

    /// Rounds to the nearest integral value, with halfway values rounded to even.
    ///
    /// Ties choose the even neighboring integer, avoiding a systematic upward
    /// or downward bias. Infinity and NaN are returned unchanged.
    ///
    /// # Example
    ///
    /// Round a displayed measurement
    ///
    /// ```splitscript
    /// let visibleDistance = 12.5.round()
    /// ```
    @intrinsic(FloatRound)
    fn round() -> Self;

    /// Rounds to a requested number of digits after the decimal point.
    ///
    /// Halfway values are rounded to even. If the decimal scale or scaled value
    /// cannot be represented finitely, the receiver is returned unchanged.
    ///
    /// # Example
    ///
    /// Keep two decimal places
    ///
    /// ```splitscript
    /// let percentage = 0.7468.roundTo(2)
    /// ```
    fn roundTo(
        /// The number of digits to preserve after the decimal point.
        decimalPlaces: u32,
    ) -> Self {
        let scale = 1
        let remaining = decimalPlaces
        while remaining > 0 {
            let next = scale * 10
            if !next.isFinite() {
                return self
            }
            scale = next
            remaining -= 1
        }
        let scaled = self * scale
        if !scaled.isFinite() {
            return self
        }
        return scaled.round() / scale
    }

    /// Returns whether the receiver is the floating-point not-a-number value.
    ///
    /// NaN is the only floating-point value that does not compare equal to itself.
    ///
    /// # Example
    ///
    /// Reject an invalid measurement
    ///
    /// ```splitscript
    /// let measurement = "NaN".parse<f64>() else 0.0
    /// if measurement.isNaN() {
    ///     print("invalid measurement")
    /// }
    /// ```
    fn isNaN() -> bool {
        return self != self
    }

    /// Returns whether the receiver is neither infinity nor NaN.
    ///
    /// Both positive and negative finite values, including signed zero, return true.
    ///
    /// # Example
    ///
    /// Use a finite measurement
    ///
    /// ```splitscript
    /// if (-12.5).isFinite() {
    ///     let magnitude = (-12.5).abs()
    /// }
    /// ```
    fn isFinite() -> bool {
        return self - self == 0
    }
}

extend f32 {
    /// The canonical 32-bit not-a-number value.
    ///
    /// NaN represents an undefined or unrepresentable floating-point result.
    /// It is not equal to itself; use [`Float.isNaN`] when testing a value.
    ///
    /// # Example
    ///
    /// Initialize an unavailable measurement
    ///
    /// ```splitscript
    /// let measurement = f32.NaN
    /// if measurement.isNaN() {
    ///     print("measurement unavailable")
    /// }
    /// ```
    const NaN: f32 = f32.fromBits(0x7fc00000);

    /// Positive infinity as a 32-bit floating-point value.
    ///
    /// This value compares greater than every finite 32-bit float and remains
    /// infinite under operations such as addition by a finite value.
    ///
    /// # Example
    ///
    /// Start an unbounded minimum search
    ///
    /// ```splitscript
    /// let minimum = f32.positiveInfinity
    /// ```
    const positiveInfinity: f32 = f32.fromBits(0x7f800000);

    /// Negative infinity as a 32-bit floating-point value.
    ///
    /// This value compares less than every finite 32-bit float. Negating it
    /// produces [`f32.positiveInfinity`].
    ///
    /// # Example
    ///
    /// Start an unbounded maximum search
    ///
    /// ```splitscript
    /// let maximum = f32.negativeInfinity
    /// ```
    const negativeInfinity: f32 = f32.fromBits(0xff800000);

    /// Constructs a 32-bit float from its exact IEEE-754 bit pattern.
    ///
    /// Every bit pattern is accepted, including signed zero, infinities, and
    /// NaN payloads. This is a reinterpretation and performs no numeric
    /// conversion.
    ///
    /// # Example
    ///
    /// Construct the smallest positive 32-bit subnormal
    ///
    /// ```splitscript
    /// let smallest = f32.fromBits(0x00000001)
    /// ```
    @mustUse("The constructed floating-point value must be used.")
    @intrinsic(F32FromBits)
    static fn fromBits(
        /// The exact IEEE-754 binary32 representation.
        bits: u32,
    ) -> f32;

    /// Returns this float's exact IEEE-754 bit pattern.
    ///
    /// Signed zero and NaN payload bits are preserved. This is a
    /// reinterpretation and performs no numeric conversion.
    ///
    /// # Example
    ///
    /// Inspect a 32-bit float
    ///
    /// ```splitscript
    /// let bits = (-0.0 as f32).toBits()
    /// ```
    @mustUse("The returned bit pattern must be used.")
    @intrinsic(F32ToBits)
    fn toBits() -> u32;
}

extend f64 {
    /// The canonical 64-bit not-a-number value.
    ///
    /// NaN represents an undefined or unrepresentable floating-point result.
    /// It is not equal to itself; use [`Float.isNaN`] when testing a value.
    ///
    /// # Example
    ///
    /// Initialize an unavailable measurement
    ///
    /// ```splitscript
    /// let measurement = f64.NaN
    /// if measurement.isNaN() {
    ///     print("measurement unavailable")
    /// }
    /// ```
    const NaN: f64 = f64.fromBits(0x7ff8000000000000u64);

    /// Positive infinity as a 64-bit floating-point value.
    ///
    /// This value compares greater than every finite 64-bit float and remains
    /// infinite under operations such as addition by a finite value.
    ///
    /// # Example
    ///
    /// Start an unbounded minimum search
    ///
    /// ```splitscript
    /// let minimum = f64.positiveInfinity
    /// ```
    const positiveInfinity: f64 = f64.fromBits(0x7ff0000000000000u64);

    /// Negative infinity as a 64-bit floating-point value.
    ///
    /// This value compares less than every finite 64-bit float. Negating it
    /// produces [`f64.positiveInfinity`].
    ///
    /// # Example
    ///
    /// Start an unbounded maximum search
    ///
    /// ```splitscript
    /// let maximum = f64.negativeInfinity
    /// ```
    const negativeInfinity: f64 = f64.fromBits(0xfff0000000000000u64);

    /// Constructs a 64-bit float from its exact IEEE-754 bit pattern.
    ///
    /// Every bit pattern is accepted, including signed zero, infinities, and
    /// NaN payloads. This is a reinterpretation and performs no numeric
    /// conversion.
    ///
    /// # Example
    ///
    /// Construct the smallest positive 64-bit subnormal
    ///
    /// ```splitscript
    /// let smallest = f64.fromBits(0x0000000000000001u64)
    /// ```
    @mustUse("The constructed floating-point value must be used.")
    @intrinsic(F64FromBits)
    static fn fromBits(
        /// The exact IEEE-754 binary64 representation.
        bits: u64,
    ) -> f64;

    /// Returns this float's exact IEEE-754 bit pattern.
    ///
    /// Signed zero and NaN payload bits are preserved. This is a
    /// reinterpretation and performs no numeric conversion.
    ///
    /// # Example
    ///
    /// Inspect a 64-bit float
    ///
    /// ```splitscript
    /// let bits = (-0.0 as f64).toBits()
    /// ```
    @mustUse("The returned bit pattern must be used.")
    @intrinsic(F64ToBits)
    fn toBits() -> u64;
}

extend bool {
    /// Inverts a boolean value.
    ///
    /// This method is also the implementation of the
    /// [`!`](operator@bool.not) operator.
    ///
    /// # Example
    ///
    /// Invert a loading flag
    ///
    /// ```splitscript
    /// let isPlaying = !false
    /// ```
    @intrinsic(BoolNot)
    @operator(not)
    fn not() -> bool;
}

/// Supports equality comparison.
///
/// Equality is available for values whose representation can be compared safely.
///
/// # Example
///
/// Compare two values
///
/// ```splitscript
/// let sameRoom = 4 == 4
/// ```
@behavior(structuralEquality)
capability Equatable {
    /// Reports whether this value and another value are equal.
    ///
    /// This method is also the implementation of the
    /// [`==`](operator@Equatable.equals) operator. Structs,
    /// enums, arrays, options, and results compare their complete structure;
    /// strings compare UTF-8 contents. Array equality compares lengths and then
    /// elements in order. Floating-point equality follows IEEE 754, so NaN is
    /// not equal to itself.
    ///
    /// # Example
    ///
    /// Compare two state values
    ///
    /// ```splitscript
    /// let unchanged = 4u32 == 4u32
    /// ```
    @intrinsic(EquatableEquals)
    @operator(equal)
    fn equals(
        /// The other value of the same type.
        other: Self,
    ) -> bool;

    /// Reports whether this value and another value differ.
    ///
    /// This method is also the implementation of the
    /// [`!=`](operator@Equatable.notEquals) operator and is the logical inverse
    /// of [`Equatable.equals`] for every [`Equatable`] type.
    ///
    /// # Example
    ///
    /// Detect a state transition
    ///
    /// ```splitscript
    /// let changed = 4u32 != 5u32
    /// ```
    @intrinsic(EquatableNotEquals)
    @operator(notEqual)
    fn notEquals(
        /// The other value of the same type.
        other: Self,
    ) -> bool;
}

/// Produces an unambiguous structural representation of a value.
///
/// [`String`] and [`char`] values are quoted and escaped. Source structs, enums,
/// and immutable managed class snapshots derive a multiline representation
/// recursively. Conditional managed fields appear only while their declared
/// attachment shape is active. Standard-library containers may opt into the
/// same structural representation for their public contents. Every other
/// runtime value receives a stable opaque representation automatically;
/// managed references, iterator cursors, and closures therefore remain
/// printable without exposing remote addresses, private traversal state, or
/// captured values.
///
/// Every [`Debug`] value also implements [`Display`]. A custom
/// [`Display.toString`] remains the user-facing representation, while
/// [`Debug.debugString`] controls how a value appears inside another derived
/// value.
///
/// # Example
///
/// Preserve quotes around nested text
///
/// ```splitscript
/// let checkpoints = ["forest", "castle"]
/// print(checkpoints)
/// ```
@behavior(structuralMethods)
capability Debug: Display {
    /// Converts the receiver to its unambiguous structural representation.
    ///
    /// User structs, enums, and managed class snapshots receive a recursive
    /// derived implementation when this method is absent. Defining an exact
    /// method with this signature overrides that representation without
    /// changing the user-facing [`Display.toString`] method.
    ///
    /// # Example
    ///
    /// Customize nested diagnostics
    ///
    /// ```splitscript
    /// state "example.exe" {}
    ///
    /// struct Checkpoint {
    ///     name: String,
    /// }
    ///
    /// fn Checkpoint.debugString() -> String {
    ///     return `Checkpoint({self.name})`
    /// }
    /// ```
    fn debugString() -> String;
}

/// Supports conversion to a user-facing textual representation.
///
/// An [`as`] [`String`] cast, string interpolation, [`print`], and
/// [`setVariable`] all display values through this single capability.
/// Source structs, enums, and opted-in standard-library containers fall back
/// to their derived [`Debug`] representation when no exact
/// [`Display.toString`] implementation exists.
///
/// # Example
///
/// Display a value without an explicit string conversion
///
/// ```splitscript
/// let scoreText = `Score: {42}`
/// ```
@behavior(structuralMethods)
capability Display {
    /// Converts the receiver to its user-facing string representation.
    ///
    /// A user struct or enum falls back to its derived [`Debug`] representation
    /// when this method is absent. Defining a method with this signature
    /// overrides that fallback. The [`String`] result may be inferred from the
    /// body, and no separate implementation declaration or annotation is needed.
    /// [`Display.toString`] powers [`as`] [`String`] casts, interpolation, [`print`],
    /// and [`setVariable`].
    ///
    /// # Example
    ///
    /// Display a user-defined position
    ///
    /// ```splitscript
    /// struct Position {
    ///     x: i32,
    ///     y: i32,
    /// }
    ///
    /// fn Position.toString() -> String {
    ///     return `({self.x}, {self.y})`
    /// }
    ///
    /// state "game.exe" {}
    /// onAttach {
    ///     let positionText = Position { x: 3, y: 5 } as String
    ///     print(positionText)
    /// }
    /// ```
    fn toString() -> String;
}

/// Reads a value selected by bracket indexing.
///
/// The implementing type chooses one key type and one returned value type.
/// Arrays use [`u32`] keys, while maps use their declared key type. Source
/// structs can participate by defining an exact [`Index.at`] method.
///
/// # Example
///
/// Read an indexed value
///
/// ```splitscript
/// let names = ["Ada", "Grace"]
/// let first = names[0]
/// ```
@behavior(structuralMethods)
capability Index {
    /// Value accepted between `[` and `]`.
    type Key;

    /// Value produced by indexed access.
    type Value;

    /// Reads the value selected by a key.
    ///
    /// Bracket indexing dispatches to this operation. The standard array and
    /// map implementations trap for an invalid index or absent key.
    ///
    /// # Example
    ///
    /// Read through an index
    ///
    /// ```splitscript
    /// let first = [10, 20].at(0)
    /// ```
    fn at(
        /// Key selecting one value.
        key: Key,
    ) -> Value;
}

/// Replaces or inserts a value through bracket assignment.
///
/// Every assignable index is also readable and therefore shares the exact
/// `Index.Key` and `Index.Value` types. Source structs participate by defining
/// both the inherited [`Index.at`] method and an exact [`IndexAssign.set`]
/// method.
///
/// # Example
///
/// Assign through an index
///
/// ```splitscript
/// let scores = Map.new<String, u32>()
/// scores["Ada"] = 12
/// ```
@behavior(structuralMethods)
capability IndexAssign: Index {
    /// Stores a value selected by a key.
    ///
    /// Plain bracket assignment invokes only this operation. Compound
    /// assignment reads with [`Index.at`], applies its operator, then invokes
    /// this operation, evaluating the receiver and key once.
    ///
    /// # Example
    ///
    /// Assign through an index
    ///
    /// ```splitscript
    /// let values = [10, 20]
    /// values.set(0, 30)
    /// ```
    fn set(
        /// Key selecting the destination.
        key: Key,
        /// New value to store.
        value: Value,
    ) -> None;
}

/// Produces a sequence of values one step at a time.
///
/// Its associated item type is the value yielded by [`Iterator.next`].
/// Exhaustion is represented by the [`End`] step, not
/// by [`None`], so iterating a sequence of optional values preserves an actual
/// [`None`] item.
///
/// # Example
///
/// Advance an iterator cursor
///
/// ```splitscript
/// state "game.exe" {}
///
/// onAttach {
///     let iterator = [1, 2].iterator()
///     let step = iterator.next()
/// }
/// ```
@behavior(structuralMethods)
capability Iterator {
    /// The value produced by one successful iterator step.
    type Item;

    /// Advances this cursor and returns either its next [`Item`] or [`End`].
    ///
    /// Repeated calls continue from the cursor's current position.
    ///
    /// # Example
    ///
    /// Read one iterator step
    ///
    /// ```splitscript
    /// state "game.exe" {}
    ///
    /// onAttach {
    ///     let iterator = (10..<12).iterator()
    ///     let first = iterator.next()
    /// }
    /// ```
    @mustUse("The yielded item or exhausted state must be inspected.")
    fn next() -> IteratorStep<Item>;

    /// Lazily transforms every remaining item from this cursor.
    ///
    /// The callback runs only when the returned iterator is advanced. The
    /// original cursor becomes the source owned by that adapter, so iterating
    /// the adapter continues from its current position.
    ///
    /// # Example
    ///
    /// Double values as they are consumed
    ///
    /// ```splitscript
    /// let doubled = [1, 2, 3].iterator().map(value => value * 2)
    /// for value in doubled {
    ///     print(value)
    /// }
    /// ```
    @mustUse("The lazy mapped iterator is otherwise discarded.")
    fn map<U>(
        /// Transformation applied to each yielded item.
        transform: (Item) -> U,
    ) -> iterator U {
        loop {
            let value = match self.next() {
                Item(value) => value,
                End => return,
            }
            yield (transform)(value)
        }
    }

    /// Lazily retains the remaining items accepted by a predicate.
    ///
    /// Advancing the returned iterator advances the source until either an
    /// accepted item or [`End`] is reached.
    ///
    /// # Example
    ///
    /// Keep even values
    ///
    /// ```splitscript
    /// let evens = [1, 2, 3, 4].iterator().filter(value => value % 2 == 0)
    /// for value in evens {
    ///     print(value)
    /// }
    /// ```
    @mustUse("The lazy filtered iterator is otherwise discarded.")
    fn filter(
        /// Predicate deciding whether an item is yielded.
        predicate: (Item) -> bool,
    ) -> iterator Item {
        loop {
            let value = match self.next() {
                Item(value) => value,
                End => return,
            }
            if (predicate)(value) {
                yield value
            }
        }
    }
}

/// Creates an [`Iterator`] over a value without consuming that value.
///
/// Arrays, sets, and integer ranges provide this capability. The iterator is
/// a first-class value with its own cursor, so it can be stored or passed to a
/// helper independently of the source collection.
///
/// # Example
///
/// Iterate over a value
///
/// ```splitscript
/// state "game.exe" {}
///
/// onAttach {
///     for value in [1, 2] {
///         print(value)
///     }
/// }
/// ```
@behavior(structuralMethods)
capability Iterable {
    /// The type-erased cursor returned for this iterable value.
    type Iterator: Iterator;

    /// Creates an independent cursor over this value.
    ///
    /// Advancing the cursor does not consume the iterable value itself.
    ///
    /// # Example
    ///
    /// Create a cursor
    ///
    /// ```splitscript
    /// state "game.exe" {}
    ///
    /// onAttach {
    ///     let iterator = [1, 2].iterator()
    /// }
    /// ```
    @mustUse("The newly created iterator cursor is otherwise discarded.")
    fn iterator() -> Iterator;
}

/// Distinguishes one yielded item from iterator exhaustion.
///
/// This wrapper deliberately remains distinct from [`T?`]: an
/// iterator whose item type is optional must be able to yield [`None`] before
/// eventually reaching the [`End`] step.
///
/// # Example
///
/// Inspect an iterator step
///
/// ```splitscript
/// let iterator = [10, 20].iterator()
/// let text = match iterator.next() {
///     Item(value) => `item {value}`,
///     End => "finished",
/// }
/// ```
@capabilities(Debug)
typeConstructor IteratorStep<T> {
    /// Compiler-private payload used by the `Item(value)` variant.
    private value: T,
}

/// Iterates over an array while detecting structural mutation.
///
/// # Example
///
/// Name an array cursor in an interface
///
/// ```splitscript
/// state "game.exe" {}
///
/// fn inspect(iterator: ArrayIterator<u32>) {}
/// ```
@capabilities(Iterator, Iterable)
private typeConstructor ArrayIterator<T> {
    /// The array element yielded by this cursor.
    type Item = T;
    /// This cursor is its own iterable representation.
    type Iterator = ArrayIterator<T>;

    /// Array whose elements are visited by this cursor.
    private source: [T],
    /// Index of the next element.
    private index: u32,
    /// Structural version captured when the cursor was created.
    private version: u32,

    /// Advances to the next array element.
    ///
    /// Structural array mutation invalidates this cursor.
    ///
    /// # Example
    ///
    /// Advance an array cursor
    ///
    /// ```splitscript
    /// let iterator = [10, 20].iterator()
    /// let step = iterator.next()
    /// ```
    @intrinsic(ArrayIteratorNext)
    @mustUse("The yielded item or exhausted state must be inspected.")
    fn next() -> IteratorStep<T>;

    /// Returns this cursor without restarting array traversal.
    ///
    /// The returned value aliases the same structural-version and index state.
    ///
    /// # Example
    ///
    /// Preserve an array cursor's position
    ///
    /// ```splitscript
    /// let cursor = [10, 20].iterator()
    /// let sameCursor = cursor.iterator()
    /// ```
    @mustUse("The iterator cursor is otherwise discarded.")
    fn iterator() -> iterator T {
        loop {
            let value = match self.next() {
                Item(value) => value,
                End => return,
            }
            yield value
        }
    }
}

/// Iterates over a set while detecting structural mutation.
///
/// # Example
///
/// Name a set cursor in an interface
///
/// ```splitscript
/// state "game.exe" {}
///
/// fn inspect(iterator: SetIterator<String>) {}
/// ```
@capabilities(Iterator, Iterable)
private typeConstructor SetIterator<T: Equatable> {
    /// The set element yielded by this cursor.
    type Item = T;
    /// This cursor is its own iterable representation.
    type Iterator = SetIterator<T>;

    /// Set whose elements are visited by this cursor.
    private source: Set<T>,
    /// Backing-array index of the next element.
    private index: u32,
    /// Structural version captured when the cursor was created.
    private version: u32,

    /// Advances to the next set element.
    ///
    /// Structural set mutation invalidates this cursor.
    ///
    /// # Example
    ///
    /// Advance a set cursor
    ///
    /// ```splitscript
    /// let values = Set.new<String>()
    /// let iterator = values.iterator()
    /// let step = iterator.next()
    /// ```
    @intrinsic(SetIteratorNext)
    @mustUse("The yielded item or exhausted state must be inspected.")
    fn next() -> IteratorStep<T>;

    /// Returns this cursor without restarting set traversal.
    ///
    /// The returned value aliases the same structural-version and index state.
    ///
    /// # Example
    ///
    /// Preserve a set cursor's position
    ///
    /// ```splitscript
    /// let values = Set.new<String>()
    /// let cursor = values.iterator()
    /// let sameCursor = cursor.iterator()
    /// ```
    @mustUse("The iterator cursor is otherwise discarded.")
    fn iterator() -> iterator T {
        loop {
            let value = match self.next() {
                Item(value) => value,
                End => return,
            }
            yield value
        }
    }
}

/// Iterates from an included integer start to an excluded end.
///
/// # Example
///
/// Name an exclusive-range cursor in an interface
///
/// ```splitscript
/// state "game.exe" {}
///
/// fn inspect(iterator: ExclusiveRangeIterator<u16>) {}
/// ```
@capabilities(Iterator, Iterable)
private typeConstructor ExclusiveRangeIterator<T: Integer> {
    /// The integer yielded by this cursor.
    type Item = T;
    /// This cursor is its own iterable representation.
    type Iterator = ExclusiveRangeIterator<T>;

    /// Next integer to yield.
    private current: T,
    /// Excluded upper endpoint.
    private end: T,

    /// Advances to the next integer before the excluded endpoint.
    ///
    /// The cursor returns [`End`] once its current value reaches the endpoint.
    ///
    /// # Example
    ///
    /// Advance an exclusive-range cursor
    ///
    /// ```splitscript
    /// let iterator = (1..<3).iterator()
    /// let step = iterator.next()
    /// ```
    @intrinsic(ExclusiveRangeIteratorNext)
    @mustUse("The yielded item or exhausted state must be inspected.")
    fn next() -> IteratorStep<T>;

    /// Returns this cursor without restarting range traversal.
    ///
    /// The returned value aliases the same current endpoint state.
    ///
    /// # Example
    ///
    /// Preserve an exclusive-range cursor's position
    ///
    /// ```splitscript
    /// let cursor = (1..<3).iterator()
    /// let sameCursor = cursor.iterator()
    /// ```
    @mustUse("The iterator cursor is otherwise discarded.")
    fn iterator() -> iterator T {
        loop {
            let value = match self.next() {
                Item(value) => value,
                End => return,
            }
            yield value
        }
    }
}

/// Iterates from an included integer start through an included end.
///
/// # Example
///
/// Name an inclusive-range cursor in an interface
///
/// ```splitscript
/// state "game.exe" {}
///
/// fn inspect(iterator: InclusiveRangeIterator<u16>) {}
/// ```
@capabilities(Iterator, Iterable)
private typeConstructor InclusiveRangeIterator<T: Integer> {
    /// The integer yielded by this cursor.
    type Item = T;
    /// This cursor is its own iterable representation.
    type Iterator = InclusiveRangeIterator<T>;

    /// Next integer to yield.
    private current: T,
    /// Included upper endpoint.
    private end: T,
    /// Whether the included endpoint has already been yielded.
    private finished: bool,

    /// Advances to the next integer through the included endpoint.
    ///
    /// The cursor returns the endpoint once before returning [`End`].
    ///
    /// # Example
    ///
    /// Advance an inclusive-range cursor
    ///
    /// ```splitscript
    /// let iterator = (1..=3).iterator()
    /// let step = iterator.next()
    /// ```
    @intrinsic(InclusiveRangeIteratorNext)
    @mustUse("The yielded item or exhausted state must be inspected.")
    fn next() -> IteratorStep<T>;

    /// Returns this cursor without restarting range traversal.
    ///
    /// The returned value aliases the same current and finished state.
    ///
    /// # Example
    ///
    /// Preserve an inclusive-range cursor's position
    ///
    /// ```splitscript
    /// let cursor = (1..=3).iterator()
    /// let sameCursor = cursor.iterator()
    /// ```
    @mustUse("The iterator cursor is otherwise discarded.")
    fn iterator() -> iterator T {
        loop {
            let value = match self.next() {
                Item(value) => value,
                End => return,
            }
            yield value
        }
    }
}

/// Supports deserialization from process memory.
///
/// Fixed-layout primitives, [`struct`]s whose fields are all readable, fixed
/// arrays, and integer-represented [`enum`]s can be selected by
/// [`Process.read`]. Declare a process-readable enum as, for example,
/// `enum GameState: i32 { Menu = 0, Playing = 1 }`. An unknown enum
/// discriminant makes the complete enclosing read fail.
///
/// # Example
///
/// Infer a readable memory type
///
/// ```splitscript
/// let health = process.read<i32>(0x1234) else 0
/// ```
@behavior(structuralMemoryLayout)
capability MemoryReadable {}

/// Reads typed values and bounded strings from an address space.
///
/// [`MemoryReader`] is the source-side counterpart to [`MemoryReadable`]. The
/// reader chooses the address domain, byte order, address validation, and
/// physical read implementation; the requested value chooses the decoded
/// memory layout. Native [`Process`] values use [`address`], while emulator
/// providers use original guest addresses represented as [`u32`].
///
/// Process-only facilities such as modules, mapped-range enumeration, and
/// scanning are deliberately not part of this capability.
///
/// # Example
///
/// Read text through a generic memory provider
///
/// ```splitscript
/// # state "game.exe" {}
/// fn readName(reader, address) {
///     return reader.readUtf8(address, 32)
/// }
/// ```
@behavior(structuralMethods)
capability MemoryReader {
    /// The address value accepted by this reader.
    type Address;

    /// Reads one fixed-layout value from this address space.
    ///
    /// The expected [`MemoryReadable`] type determines the requested layout.
    /// Invalid addresses, inaccessible memory, and invalid enum discriminants
    /// return an error.
    ///
    /// # Example
    ///
    /// Read a native integer
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// # onAttach {
    /// let score = process.read<u32>(0x1000) else 0
    /// # print(score)
    /// # }
    /// ```
    fn read<U: MemoryReadable>(
        /// Address in this reader's native domain.
        address: Address,
    ) -> U!;

    /// Reads a bounded NUL-terminated UTF-8 string.
    ///
    /// At most `maxBytes` are read in one operation. Decoding stops at the
    /// first NUL byte. Failed memory access, a zero or excessive bound, or
    /// invalid UTF-8 returns an error. The result is an ordinary immutable
    /// [`String`].
    ///
    /// # Example
    ///
    /// Read a map name from native process memory
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// # onAttach {
    /// let map = process.readUtf8(0x1000, 32) else "Unknown"
    /// # print(map)
    /// # }
    /// ```
    @requires(attachedProcess)
    @intrinsic(MemoryReaderReadUtf8)
    fn readUtf8(
        /// Address of the first UTF-8 byte.
        address: Address,
        /// Maximum number of bytes to read, from 1 through 4096.
        maxBytes: u32,
    ) -> String!;

    /// Reads a bounded NUL-terminated little-endian UTF-16 string.
    ///
    /// At most `maxUtf16Units` code units are read in one operation. Decoding
    /// stops at the first NUL code unit. Failed memory access, a zero or
    /// excessive bound returns an error. Unpaired surrogate code units become
    /// the Unicode replacement character.
    ///
    /// # Example
    ///
    /// Read a native Windows string
    ///
    /// ```splitscript
    /// # state "game.exe" {}
    /// # onAttach {
    /// let chapter = process.readUtf16Le(0x1000, 64) else "Unknown"
    /// # print(chapter)
    /// # }
    /// ```
    @requires(attachedProcess)
    @intrinsic(MemoryReaderReadUtf16Le)
    fn readUtf16Le(
        /// Address of the first little-endian UTF-16 code unit.
        address: Address,
        /// Maximum number of code units to read, from 1 through 2048.
        maxUtf16Units: u32,
    ) -> String!;
}

/// Stores an indexed sequence of values.
///
/// [`[T]`] creates growable values, while [`[T; N]`] carries an exact length and
/// can provide a fixed process-memory layout. An omitted shape in a helper
/// parameter is inferred, so read-only helpers accept both forms without
/// erasing an exact length. Structural mutation constrains the receiver to a
/// growable array. Both forms use WebAssembly GC storage and expose the same
/// length, indexed access, element replacement, search, and iteration APIs.
///
/// # Example
///
/// Store a typed sequence
///
/// ```splitscript
/// let inventory: [u8] = [1, 2, 3]
/// ```
@capabilities(Debug, Iterable, IndexAssign)
typeConstructor [T] {
    /// Index accepted by bracket access.
    type Key = u32;
    /// Value read or written through an index.
    type Value = T;
    /// The cursor created for this array.
    type Iterator = iterator T;

    // Constructs the representation-specific cursor used only by the standard
    // library's type-erasure adapter below.
    @intrinsic(ArrayIterator)
    private fn rawIterator() -> ArrayIterator<T>;

    /// Creates an independent cursor over this array.
    ///
    /// The cursor initially points at index zero and captures the array's structural version.
    ///
    /// # Example
    ///
    /// Iterate manually
    ///
    /// ```splitscript
    /// let iterator = ["forest", "castle"].iterator()
    /// ```
    @mustUse("The newly created iterator cursor is otherwise discarded.")
    fn iterator() -> iterator T {
        return self.rawIterator().iterator()
    }

    /// Returns the number of array elements.
    ///
    /// The result is the WebAssembly GC array length.
    ///
    /// # Example
    ///
    /// Count array elements
    ///
    /// ```splitscript
    /// let fieldCount = ["health", "mana"].length()
    /// ```
    @intrinsic(ArrayLength)
    fn length() -> u32;

    /// Reports whether the array contains no elements.
    ///
    /// This is ordinary library composition over
    /// [`[T].length`](method@Array.length); it does not require a separate
    /// runtime intrinsic.
    ///
    /// # Example
    ///
    /// Check for an empty array
    ///
    /// ```splitscript
    /// let fieldNames: [String] = []
    /// let hasNoFields = fieldNames.isEmpty()
    /// ```
    fn isEmpty() -> bool {
        return self.length() == 0
    }

    /// Reports whether the array contains an equal element.
    ///
    /// Elements are compared from the beginning of the array. The element
    /// type must support equality.
    ///
    /// # Example
    ///
    /// Check a closed route table
    ///
    /// ```splitscript
    /// let route = [2, 4, 7]
    /// let visitsBoss = route.contains(7)
    /// ```
    fn contains(
        /// The element to find.
        value: T,
    ) -> bool where T: Equatable {
        for element in self {
            if element == value {
                return true
            }
        }
        return false
    }

    /// Finds the first index containing an equal element.
    ///
    /// Returns [`None`] when the value is absent. The index is a [`u32`], matching
    /// the array indexing and length APIs, and the element type must support
    /// equality.
    ///
    /// # Example
    ///
    /// Find a checkpoint in a route table
    ///
    /// ```splitscript
    /// let route = [2, 4, 7]
    /// let bossIndex = route.indexOf(7)
    /// ```
    fn indexOf(
        /// The element to find.
        value: T,
    ) -> u32? where T: Equatable {
        let index = 0
        while index < self.length() {
            if self[index] == value {
                return index
            }
            index += 1
        }
        return None
    }

    // Implements array indexing while direct concrete array access retains
    // its allocation-free compiler lowering.
    private fn at(index: u32) -> T {
        return self[index]
    }

    /// Updates an array element.
    ///
    /// This is the standard-library operation behind an [`array indexing`]
    /// assignment.
    /// The array and index are evaluated once and the element is updated in
    /// place without structurally invalidating active iteration.
    ///
    /// # Example
    ///
    /// Replace an array element
    ///
    /// ```splitscript
    /// let fieldNames = ["mana"]
    /// fieldNames.set(0, "health")
    /// ```
    @intrinsic(ArraySet)
    fn set(
        /// The zero-based element index.
        index: u32,
        /// The new element value.
        value: T,
    ) -> None;

    /// Appends an element to a growable array.
    ///
    /// Capacity grows geometrically when needed, while the array value keeps
    /// the same identity so every alias observes the appended element.
    /// Exact [`[T; N]`] arrays cannot change length and do not support [`push`].
    /// Appending through any alias invalidates active iteration of this array.
    ///
    /// # Example
    ///
    /// Append a discovered checkpoint
    ///
    /// ```splitscript
    /// let checkpoints: [u32] = [1, 2]
    /// checkpoints.push(3)
    /// ```
    @intrinsic(ArrayPush)
    fn push(
        /// The element to append.
        value: T,
    ) -> None;

    /// Appends every element from another array.
    ///
    /// The source length is captured before appending, so extending an array
    /// with itself duplicates its original elements exactly once. The receiver
    /// keeps its identity and grows with the same amortized behavior as
    /// [`push`]. Exact [`[T; N]`] arrays cannot change length and do not support
    /// [`extend`]. Extending through any alias invalidates active iteration of
    /// the receiver.
    ///
    /// # Example
    ///
    /// Append discovered checkpoints in bulk
    ///
    /// ```splitscript
    /// let checkpoints: [u32] = [1, 2]
    /// checkpoints.extend([4, 7, 9])
    /// ```
    fn extend(
        /// The elements to append, in order.
        values: [T],
    ) -> None {
        let count = values.length()
        let index = 0
        while index < count {
            self.push(values[index])
            index += 1
        }
    }

    /// Removes the element at an index and shifts later elements left.
    ///
    /// The array keeps its identity and capacity, so aliases observe the
    /// removal. An index greater than or equal to
    /// [`[T].length`](method@Array.length) traps, matching indexed access. Stored
    /// references in the vacated final slot are
    /// released for garbage collection. Exact [`[T; N]`] arrays cannot change
    /// length and do not support [`removeAt`].
    ///
    /// # Example
    ///
    /// Consume the first pending checkpoint
    ///
    /// ```splitscript
    /// let checkpoints: [u32] = [1, 2]
    /// checkpoints.removeAt(0)
    /// ```
    @intrinsic(ArrayRemoveAt)
    fn removeAt(
        /// The zero-based index to remove.
        index: u32,
    ) -> None;

    /// Removes the first element equal to a value.
    ///
    /// Returns whether an element was removed. Elements are searched from the
    /// beginning, duplicates after the first match remain in place, and an
    /// absent value leaves the array unchanged. The receiver keeps its identity
    /// and capacity. Exact [`[T; N]`] arrays cannot change length and do not
    /// support [`[T].remove`](method@Array.remove).
    ///
    /// # Example
    ///
    /// Consume one completed checkpoint
    ///
    /// ```splitscript
    /// let pendingCheckpoints = ["forest", "castle"]
    /// let removed = pendingCheckpoints.remove("forest")
    /// ```
    fn remove(
        /// The first equal element to remove.
        value: T,
    ) -> bool where T: Equatable {
        let index = self.indexOf(value) else return false
        self.removeAt(index)
        return true
    }

    /// Removes and returns the final element when one exists.
    ///
    /// An empty array returns [`None`] without changing its structural version.
    /// Otherwise the array keeps its identity and capacity, aliases observe
    /// the shorter length, and active iteration is invalidated. Exact [`[T; N]`]
    /// arrays cannot change length and do not support [`pop`].
    ///
    /// # Example
    ///
    /// Consume the most recently discovered checkpoint
    ///
    /// ```splitscript
    /// let checkpoints: [u32] = [1, 2]
    /// let checkpoint = checkpoints.pop() else return
    /// ```
    fn pop() -> T? {
        let length = self.length()
        let value = if length == 0 {
            None
        } else {
            Some(self[length - 1])
        }
        if length != 0 {
            self.removeAt(length - 1)
        }
        return value
    }

    /// Removes every element from a growable array.
    ///
    /// The array keeps its identity and capacity, so aliases observe the empty
    /// result and later appends can reuse its storage. Stored references are
    /// released for garbage collection. Exact [`[T; N]`] arrays cannot change
    /// length and do not support [`[T].clear`](method@Array.clear).
    /// Clearing through any alias invalidates active iteration of this array.
    ///
    /// # Example
    ///
    /// Reset discovered checkpoints
    ///
    /// ```splitscript
    /// let checkpoints: [u32] = [1, 2]
    /// checkpoints.clear()
    /// ```
    @intrinsic(ArrayClear)
    fn clear() -> None;
}

/// Represents an integer interval whose upper bound is excluded.
///
/// Use [`..<`](syntax@range) when the value at `end` must not be visited.
/// Range bounds are immutable, and a range whose end precedes its start is
/// empty.
///
/// # Example
///
/// Visit array indices
///
/// ```splitscript
/// let values = ["health", "mana"]
/// for index in 0..<values.length() {
///     print(values[index])
/// }
/// ```
@capabilities(Debug, Iterable)
typeConstructor T..<T {
    /// The cursor created for this exclusive range.
    type Iterator = iterator T;

    // Constructs the representation-specific cursor used only by the standard
    // library's type-erasure adapter below.
    @intrinsic(ExclusiveRangeIterator)
    private fn rawIterator() -> ExclusiveRangeIterator<T>;

    /// Creates a cursor starting at this range's included lower endpoint.
    ///
    /// The range value remains available and unchanged.
    ///
    /// # Example
    ///
    /// Create an exclusive-range cursor
    ///
    /// ```splitscript
    /// let iterator = (1..<4).iterator()
    /// ```
    @mustUse("The newly created iterator cursor is otherwise discarded.")
    fn iterator() -> iterator T {
        return self.rawIterator().iterator()
    }

    /// Returns the included lower endpoint.
    ///
    /// Range endpoints are immutable and retain the range's exact integer type.
    ///
    /// # Example
    ///
    /// Inspect an exclusive range's beginning
    ///
    /// ```splitscript
    /// let checkpoints = 2u16..<5
    /// print(checkpoints.start)
    /// ```
    start: T,

    /// Returns the excluded upper endpoint.
    ///
    /// Iteration stops before this value. The endpoint remains available even
    /// when the range is empty.
    ///
    /// # Example
    ///
    /// Inspect an exclusive range's limit
    ///
    /// ```splitscript
    /// let checkpoints = 2u16..<5
    /// print(checkpoints.end)
    /// ```
    end: T,

    /// Reports whether a value belongs to this range.
    ///
    /// The lower endpoint participates and the upper endpoint does not.
    /// Reversed ranges contain no values.
    ///
    /// # Example
    ///
    /// Test exclusive membership
    ///
    /// ```splitscript
    /// let activeChapters = 2u8..<5
    /// let isActive = activeChapters.contains(4)
    /// ```
    fn contains(
        /// The value to test.
        value: T,
    ) -> bool {
        return self.start <= value && value < self.end
    }

    /// Reports whether this range contains no values.
    ///
    /// Equal or reversed endpoints make an exclusive range empty.
    ///
    /// # Example
    ///
    /// Detect an empty exclusive range
    ///
    /// ```splitscript
    /// let pending = 4u32..<4
    /// let finished = pending.isEmpty()
    /// ```
    fn isEmpty() -> bool {
        return self.start >= self.end
    }
}

/// Represents an integer interval whose upper bound is included.
///
/// Use [`..=`](syntax@range) when the value at `end` must be visited. Range
/// bounds are immutable, and a range whose end precedes its start is empty.
///
/// # Example
///
/// Visit both endpoints
///
/// ```splitscript
/// for checkpoint in 1..=3 {
///     print(checkpoint)
/// }
/// ```
@capabilities(Debug, Iterable)
typeConstructor T..=T {
    /// The cursor created for this inclusive range.
    type Iterator = iterator T;

    // Constructs the representation-specific cursor used only by the standard
    // library's type-erasure adapter below.
    @intrinsic(InclusiveRangeIterator)
    private fn rawIterator() -> InclusiveRangeIterator<T>;

    /// Creates a cursor starting at this range's included lower endpoint.
    ///
    /// The range value remains available and unchanged.
    ///
    /// # Example
    ///
    /// Create an inclusive-range cursor
    ///
    /// ```splitscript
    /// let iterator = (1..=4).iterator()
    /// ```
    @mustUse("The newly created iterator cursor is otherwise discarded.")
    fn iterator() -> iterator T {
        return self.rawIterator().iterator()
    }

    /// Returns the included lower endpoint.
    ///
    /// Range endpoints are immutable and retain the range's exact integer type.
    ///
    /// # Example
    ///
    /// Inspect an inclusive range's beginning
    ///
    /// ```splitscript
    /// let checkpoints = 2u16..=5
    /// print(checkpoints.start)
    /// ```
    start: T,

    /// Returns the included upper endpoint.
    ///
    /// Iteration visits this value when the range is not reversed.
    ///
    /// # Example
    ///
    /// Inspect an inclusive range's end
    ///
    /// ```splitscript
    /// let checkpoints = 2u16..=5
    /// print(checkpoints.end)
    /// ```
    end: T,

    /// Reports whether a value belongs to this range.
    ///
    /// Both endpoints participate. Reversed ranges contain no values.
    ///
    /// # Example
    ///
    /// Test inclusive membership
    ///
    /// ```splitscript
    /// let activeChapters = 2u8..=5
    /// let isActive = activeChapters.contains(5)
    /// ```
    fn contains(
        /// The value to test.
        value: T,
    ) -> bool {
        return self.start <= value && value <= self.end
    }

    /// Reports whether this range contains no values.
    ///
    /// Only reversed endpoints make an inclusive range empty; equal endpoints
    /// contain exactly one value.
    ///
    /// # Example
    ///
    /// Detect a reversed inclusive range
    ///
    /// ```splitscript
    /// let pending = 5u32..=4
    /// let finished = pending.isEmpty()
    /// ```
    fn isEmpty() -> bool {
        return self.start > self.end
    }
}

/// Stores a growable collection of unique values for one script instance.
///
/// A set keeps its allocation and contents across ticks. Mutating operations
/// update the same set value, so a global set can track visited checkpoints
/// without rebuilding a collection on every update.
///
/// # Example
///
/// Track visited rooms
///
/// ```splitscript
/// let visited = Set.new<String>()
/// visited.insert("Atrium")
/// ```
@capabilities(Debug, Iterable)
typeConstructor Set<T: Equatable> {
    /// The cursor created for this set.
    type Iterator = iterator T;

    // Constructs the representation-specific cursor used only by the standard
    // library's type-erasure adapter below.
    @intrinsic(SetIterator)
    private fn rawIterator() -> SetIterator<T>;

    /// Creates an independent cursor over this set.
    ///
    /// The cursor initially points at the set's first occupied backing slot.
    ///
    /// # Example
    ///
    /// Iterate a set manually
    ///
    /// ```splitscript
    /// let values = Set.new<String>()
    /// let iterator = values.iterator()
    /// ```
    @mustUse("The newly created iterator cursor is otherwise discarded.")
    fn iterator() -> iterator T {
        return self.rawIterator().iterator()
    }

    /// Creates an empty set.
    ///
    /// The returned value retains its contents until explicitly mutated or the
    /// script instance is unloaded.
    ///
    /// # Example
    ///
    /// Create a room set
    ///
    /// ```splitscript
    /// let visited = Set.new<String>()
    /// ```
    @intrinsic(SetNew)
    static fn new<U: Equatable>() -> Set<U>;

    /// Returns the number of stored values.
    ///
    /// Duplicate insertions do not increase the count.
    ///
    /// # Example
    ///
    /// Count visited rooms
    ///
    /// ```splitscript
    /// let visited = Set.new<String>()
    /// let roomCount = visited.length()
    /// ```
    @intrinsic(SetLength)
    fn length() -> u32;

    /// Reports whether the set contains no values.
    ///
    /// This composes the source-defined result from [`Set.length`].
    ///
    /// # Example
    ///
    /// Check a new route
    ///
    /// ```splitscript
    /// let visited = Set.new<String>()
    /// let routeIsNew = visited.isEmpty()
    /// ```
    fn isEmpty() -> bool {
        return self.length() == 0
    }

    /// Reports whether an equal value is present.
    ///
    /// Values are compared using the element type's equality implementation.
    ///
    /// # Example
    ///
    /// Check a visited room
    ///
    /// ```splitscript
    /// let visited = Set.new<String>()
    /// let seenAtrium = visited.contains("Atrium")
    /// ```
    @intrinsic(SetContains)
    fn contains(
        /// The value to find.
        value: T,
    ) -> bool;

    /// Inserts a value if it is not already present.
    ///
    /// Returns whether the value was newly inserted.
    /// A successful insertion invalidates active iteration of this set;
    /// inserting an existing value does not.
    ///
    /// # Example
    ///
    /// Record a visited room
    ///
    /// ```splitscript
    /// let visited = Set.new<String>()
    /// let firstVisit = visited.insert("Atrium")
    /// ```
    @intrinsic(SetInsert)
    fn insert(
        /// The value to insert.
        value: T,
    ) -> bool;

    /// Removes an equal value if it is present.
    ///
    /// Returns whether a value was removed.
    /// A successful removal invalidates active iteration of this set; removing
    /// a missing value does not.
    ///
    /// # Example
    ///
    /// Forget a visited room
    ///
    /// ```splitscript
    /// let visited = Set.new<String>()
    /// let wasVisited = visited.remove("Atrium")
    /// ```
    @intrinsic(SetRemove)
    fn remove(
        /// The value to remove.
        value: T,
    ) -> bool;

    /// Removes every stored value while retaining the set itself.
    ///
    /// Later insertions reuse the same logical set value.
    /// Clearing invalidates active iteration of this set.
    ///
    /// # Example
    ///
    /// Reset a route
    ///
    /// ```splitscript
    /// let visited = Set.new<String>()
    /// visited.clear()
    /// ```
    @intrinsic(SetClear)
    fn clear() -> None;
}

/// Stores one key-value pair yielded while iterating a [`Map`].
///
/// Both fields are immutable snapshots. A later replacement in the source map
/// does not change an entry that was already yielded.
///
/// # Example
///
/// Destructure a map entry
///
/// ```splitscript
/// let routes = Map.new<String, u32>()
/// routes["Atrium"] = 12
/// for { key, value } in routes {
///     print(`{key}: {value}`)
/// }
/// ```
@capabilities(Debug)
typeConstructor MapEntry<K, V> {
    /// Key stored by this entry.
    ///
    /// The key is the same value that was supplied when the entry was inserted.
    ///
    /// # Example
    ///
    /// Read an entry key
    ///
    /// ```splitscript
    /// let routes = Map.new<String, u32>()
    /// routes["Atrium"] = 12
    /// for entry in routes {
    ///     print(entry.key)
    /// }
    /// ```
    key: K,
    /// Value stored by this entry.
    ///
    /// Replacing the corresponding map entry later does not mutate this value.
    ///
    /// # Example
    ///
    /// Read an entry value
    ///
    /// ```splitscript
    /// let routes = Map.new<String, u32>()
    /// routes["Atrium"] = 12
    /// for entry in routes {
    ///     print(entry.value)
    /// }
    /// ```
    value: V,
}

/// Stores an insertion-ordered association from unique keys to values.
///
/// Keys are compared with [`Equatable`]. The representation is tuned for the
/// small and medium lookup tables common in autosplitters; no complexity
/// guarantee is part of the API. The map retains its identity and contents
/// across ticks, so aliases observe every mutation. Indexing returns the
/// stored value and traps when the key is absent; use [`Map.containsKey`] first
/// when absence is expected. This keeps maps whose values are themselves
/// optional unambiguous without adding another lookup operation.
///
/// # Example
///
/// Store and read route metadata
///
/// ```splitscript
/// let routes = Map.new<String, u32>()
/// routes["Atrium"] = 12
/// if routes.containsKey("Atrium") {
///     print(routes["Atrium"])
/// }
/// ```
@capabilities(Debug, Iterable, IndexAssign)
typeConstructor Map<K: Equatable, V> {
    /// Key accepted by bracket access.
    type Key = K;
    /// Value read or written through a key.
    type Value = V;
    /// Cursor created for this map.
    type Iterator = iterator MapEntry<K, V>;

    /// Insertion-ordered entry storage.
    private entries: [MapEntry<K, V>],

    /// Creates an empty map.
    ///
    /// The key and value types may be written explicitly or inferred from
    /// later operations.
    ///
    /// # Example
    ///
    /// Create a route lookup
    ///
    /// ```splitscript
    /// let routes = Map.new<String, u32>()
    /// ```
    static fn new<A: Equatable, B>() -> Map<A, B> {
        return Map { entries: [] }
    }

    /// Returns the number of stored key-value pairs.
    ///
    /// Replacing an existing key does not increase the count.
    ///
    /// # Example
    ///
    /// Count route entries
    ///
    /// ```splitscript
    /// let routes = Map.new<String, u32>()
    /// routes["Atrium"] = 12
    /// let count = routes.length()
    /// ```
    fn length() -> u32 {
        return self.entries.length()
    }

    /// Reports whether this map contains no entries.
    ///
    /// A newly created or cleared map is empty.
    ///
    /// # Example
    ///
    /// Check a new map
    ///
    /// ```splitscript
    /// let routes = Map.new<String, u32>()
    /// let empty = routes.isEmpty()
    /// ```
    fn isEmpty() -> bool {
        return self.entries.isEmpty()
    }

    /// Reports whether an equal key is present.
    ///
    /// Values do not participate in this lookup.
    ///
    /// # Example
    ///
    /// Check a route key
    ///
    /// ```splitscript
    /// let routes = Map.new<String, u32>()
    /// routes["Atrium"] = 12
    /// let known = routes.containsKey("Atrium")
    /// ```
    fn containsKey(
        /// Key to find.
        key: K,
    ) -> bool {
        let index = 0
        while index < self.entries.length() {
            if self.entries[index].key == key {
                return true
            }
            index += 1
        }
        return false
    }

    // Implements map indexing. A missing key traps, matching out-of-bounds
    // array indexing.
    private fn at(key: K) -> V {
        let index = 0
        while index < self.entries.length() {
            let entry = self.entries[index]
            if entry.key == key {
                return entry.value
            }
            index += 1
        }
        // Deliberately perform one out-of-bounds array access to produce the
        // same deterministic trap used by missing array indices.
        return self.entries[self.entries.length()].value
    }

    /// Inserts a key-value pair or replaces the value for an existing key.
    ///
    /// Returns `true` when a new key was inserted and `false` when an existing
    /// entry was replaced. Replacement preserves insertion order.
    ///
    /// # Example
    ///
    /// Distinguish insertion from replacement
    ///
    /// ```splitscript
    /// let routes = Map.new<String, u32>()
    /// let inserted = routes.insert("Atrium", 12)
    /// let replaced = routes.insert("Atrium", 14)
    /// ```
    fn insert(
        /// Key to insert or replace.
        key: K,
        /// Value to store for the key.
        value: V,
    ) -> bool {
        let index = 0
        while index < self.entries.length() {
            if self.entries[index].key == key {
                self.entries[index] = MapEntry { key, value }
                return false
            }
            index += 1
        }
        self.entries.push(MapEntry { key, value })
        return true
    }

    // Implements map indexed assignment without exposing a second public
    // insertion convention alongside `map[key] = value` and `insert`.
    private fn set(
        key: K,
        value: V,
    ) -> None {
        self.insert(key, value)
    }

    /// Removes the entry for a key when present.
    ///
    /// Returns whether an entry was removed. Later entries retain their
    /// relative insertion order.
    ///
    /// # Example
    ///
    /// Remove a completed route
    ///
    /// ```splitscript
    /// let routes = Map.new<String, u32>()
    /// routes["Atrium"] = 12
    /// let removed = routes.remove("Atrium")
    /// ```
    fn remove(
        /// Key whose entry should be removed.
        key: K,
    ) -> bool {
        let index = 0
        while index < self.entries.length() {
            if self.entries[index].key == key {
                self.entries.removeAt(index)
                return true
            }
            index += 1
        }
        return false
    }

    /// Removes every entry while preserving this map's identity.
    ///
    /// Every alias observes the cleared contents.
    ///
    /// # Example
    ///
    /// Clear route metadata
    ///
    /// ```splitscript
    /// let routes = Map.new<String, u32>()
    /// routes["Atrium"] = 12
    /// routes.clear()
    /// ```
    fn clear() -> None {
        self.entries.clear()
    }

    /// Creates an insertion-order cursor over this map's entries.
    ///
    /// Structural mutation through insertion of a new key, removal, or clearing
    /// invalidates the cursor through the backing array's ordinary iterator
    /// rules. Replacing an existing value preserves the cursor and order.
    ///
    /// # Example
    ///
    /// Create a map cursor
    ///
    /// ```splitscript
    /// let routes = Map.new<String, u32>()
    /// let iterator = routes.iterator()
    /// ```
    fn iterator() -> iterator MapEntry<K, V> {
        return self.entries.iterator()
    }
}

/// Represents a value that may be absent.
///
/// Write [`T?`] to make any value type optional.
///
/// # Example
///
/// Store an optional value
///
/// ```splitscript
/// let possibleLevel: u32? = 4
/// ```
@mustUse("Optional values must be inspected or explicitly discarded.")
@capabilities(Debug)
typeConstructor T? {}

/// Represents a value or an error.
///
/// Write [`T!`] to make any value type fallible.
///
/// # Example
///
/// Store a successful result
///
/// ```splitscript
/// let health: u32! = 100
/// ```
@mustUse("Fallible values must be handled so failures are not silently ignored.")
@capabilities(Debug)
typeConstructor T! {
    /// Converts a fallible value into an optional value.
    ///
    /// A success becomes the present optional value. An error becomes
    /// [`None`], discarding its diagnostic text. This is useful for state fields
    /// that are deliberately unavailable on some ticks; required fields should
    /// keep their [`T!`] so a failed read retains the last accepted field value.
    ///
    /// # Example
    ///
    /// Make one process read optional
    ///
    /// ```splitscript
    /// let health: i32? = process.read<i32>(0x1000).discardError()
    /// ```
    fn discardError() -> T? {
        return match self {
            Ok(value) => Some(value),
            Err(_) => None,
        }
    }
}

extend address {
    /// Applies a signed displacement to an address.
    ///
    /// Arithmetic wraps modulo the 64-bit address space. This preserves the
    /// full unsigned address domain while allowing negative pointer offsets.
    ///
    /// # Example
    ///
    /// Add a field offset
    ///
    /// ```splitscript
    /// let healthAddress = 0x1000.offset(0x20)
    /// ```
    fn offset<T: Integer>(
        /// The integer displacement; signed values retain their sign.
        offset: T,
    ) -> address {
        return self.add(offset as u64)
    }

    /// Adds a full-width offset to an address.
    ///
    /// This is useful for unsigned sizes and offsets already represented as
    /// [`u64`]. Arithmetic wraps modulo the 64-bit address space.
    ///
    /// # Example
    ///
    /// Add a full-width offset
    ///
    /// ```splitscript
    /// let target = 0x1000.add(0x200u64)
    /// ```
    @intrinsic(AddressAdd)
    fn add(
        /// The full-width address offset.
        offset: u64,
    ) -> address;

    /// Builds a pointer path rooted at this address.
    ///
    /// Each dereference offset is applied before reading the next native
    /// pointer. The final offset is applied without another dereference.
    ///
    /// # Example
    ///
    /// Describe a player health path
    ///
    /// ```splitscript
    /// let health = 0x1000.memoryPath([0x100, 0x20], 0x18)
    /// ```
    fn memoryPath(
        /// Signed offsets that each end in a native pointer read.
        dereferences: [i64],
        /// Signed offset applied after the final pointer read.
        finalOffset: i64,
    ) -> MemoryPath {
        return MemoryPath {
            base: self,
            dereferences,
            finalOffset
        }
    }
}

/// Stores ordinary immutable UTF-8 text in WebAssembly GC memory.
///
/// String literals, interpolation, process decoders, and timer variables all
/// produce this same type. A decoded string owns its GC storage and is not a
/// view into target-process memory. Decoder bounds such as `utf8(64)` describe
/// the memory operation, not distinct [`String`] types.
///
/// # Example
///
/// Store owned text
///
/// ```splitscript
/// let character: String = "Toree"
/// ```
@representation(gcArray, u8, mutable, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable)
@capabilities(Debug, Equatable, Display)
intrinsic type String {
    /// Returns a string's UTF-8 byte length.
    ///
    /// The result counts UTF-8 bytes in the current string representation.
    ///
    /// # Example
    ///
    /// Measure UTF-8 text
    ///
    /// ```splitscript
    /// let byteLength = "Bonus_01".byteLength()
    /// ```
    @intrinsic(StringLength)
    fn byteLength() -> u32;

    /// Reports whether this string contains no UTF-8 bytes.
    ///
    /// [`String`] itself is never absent. Use ordinary [`match`] on an optional
    /// string ([`T?`]) when absence and emptiness should both satisfy a condition.
    ///
    /// # Example
    ///
    /// Ignore an empty checkpoint name
    ///
    /// ```splitscript
    /// let hasCheckpoint = !"Forest".isEmpty()
    /// ```
    @mustUse("The string emptiness result must be used.")
    fn isEmpty() -> bool {
        return self.byteLength() == 0
    }

    /// Tests whether this string contains an exact substring.
    ///
    /// Matching is case-sensitive over the UTF-8 text. An empty substring is
    /// contained in every string.
    ///
    /// # Example
    ///
    /// Recognize a level-name fragment
    ///
    /// ```splitscript
    /// let isBonusLevel = "Bonus_01".contains("Bonus")
    /// ```
    @intrinsic(StringContains)
    fn contains(
        /// The substring to search for.
        substring: String,
    ) -> bool;

    /// Finds the first exact substring and returns its UTF-8 byte offset.
    ///
    /// Returns [`None`] when the substring is absent. An empty substring is found
    /// at byte offset zero. Searching is allocation-free and case-sensitive.
    ///
    /// # Example
    ///
    /// Find a separator in an ASCII scene identifier
    ///
    /// ```splitscript
    /// let separator = "chapter_room".indexOf("_") else return
    /// ```
    @intrinsic(StringIndexOf)
    fn indexOf(
        /// The substring to search for.
        substring: String,
    ) -> u32?;

    /// Finds the last exact substring and returns its UTF-8 byte offset.
    ///
    /// Returns [`None`] when the substring is absent. An empty substring is found
    /// at the string's final byte boundary. Searching is allocation-free and
    /// case-sensitive.
    ///
    /// # Example
    ///
    /// Find the final separator in a path
    ///
    /// ```splitscript
    /// let separator = "/game/bin/game.exe".lastIndexOf("/") else return
    /// ```
    @mustUse("The optional byte offset must be used.")
    @intrinsic(StringLastIndexOf)
    fn lastIndexOf(
        /// The substring to search for.
        substring: String,
    ) -> u32?;

    /// Tests whether this string starts with an exact prefix.
    ///
    /// Matching is case-sensitive over the UTF-8 text. Every string starts
    /// with the empty prefix.
    ///
    /// # Example
    ///
    /// Recognize challenge levels
    ///
    /// ```splitscript
    /// let isChallenge = "Challenge_01".startsWith("Challenge_")
    /// ```
    @intrinsic(StringStartsWith)
    fn startsWith(
        /// The prefix to compare.
        prefix: String,
    ) -> bool;

    /// Tests whether this string ends with an exact suffix.
    ///
    /// Matching is case-sensitive over the UTF-8 text. Every string ends with
    /// the empty suffix.
    ///
    /// # Example
    ///
    /// Recognize completed scene names
    ///
    /// ```splitscript
    /// let isCompleted = "Forest_Complete".endsWith("_Complete")
    /// ```
    @intrinsic(StringEndsWith)
    fn endsWith(
        /// The suffix to compare.
        suffix: String,
    ) -> bool;

    /// Compares two strings while ignoring ASCII letter case.
    ///
    /// Only `A` through `Z` and `a` through `z` are folded. All other UTF-8
    /// bytes must match exactly, so this operation is allocation-free and does
    /// not claim to implement Unicode case folding.
    ///
    /// # Example
    ///
    /// Match a process name with explicit ASCII semantics
    ///
    /// ```splitscript
    /// let isGame = "LUNISTICE.EXE".equalsIgnoreAsciiCase("Lunistice.exe")
    /// ```
    @intrinsic(StringEqualsIgnoreAsciiCase)
    fn equalsIgnoreAsciiCase(
        /// The string to compare.
        other: String,
    ) -> bool;

    /// Returns this string with ASCII uppercase letters converted to lowercase.
    ///
    /// Only `A` through `Z` are changed. Every other UTF-8 byte is preserved,
    /// so this operation does not claim to implement Unicode lowercasing. If
    /// the string contains no ASCII uppercase letters, the existing immutable
    /// string is reused without allocating.
    ///
    /// # Example
    ///
    /// Normalize an ASCII map identifier
    ///
    /// ```splitscript
    /// let map = "FOREST".toAsciiLowerCase()
    /// ```
    @mustUse("Strings are immutable; toAsciiLowerCase returns the normalized string and does not modify its receiver.")
    @intrinsic(StringToAsciiLowerCase)
    fn toAsciiLowerCase() -> String;

    /// Returns this string with ASCII lowercase letters converted to uppercase.
    ///
    /// Only `a` through `z` are changed. Every other UTF-8 byte is preserved,
    /// so this operation does not claim to implement Unicode uppercasing. If
    /// the string contains no ASCII lowercase letters, the existing immutable
    /// string is reused without allocating.
    ///
    /// # Example
    ///
    /// Normalize an ASCII mission identifier
    ///
    /// ```splitscript
    /// let mission = "escape".toAsciiUpperCase()
    /// ```
    @mustUse("Strings are immutable; toAsciiUpperCase returns the normalized string and does not modify its receiver.")
    @intrinsic(StringToAsciiUpperCase)
    fn toAsciiUpperCase() -> String;

    /// Removes ASCII whitespace from both ends of this string.
    ///
    /// ASCII space, tab, line feed, vertical tab, form feed, and carriage
    /// return are removed. Interior bytes and every non-ASCII character are
    /// preserved. If neither end changes, the existing immutable string is
    /// reused without allocating.
    ///
    /// # Example
    ///
    /// Clean a line read from a game log
    ///
    /// ```splitscript
    /// let eventName = "  boss defeated  ".trimAsciiWhitespace()
    /// ```
    @mustUse("Strings are immutable; trimAsciiWhitespace returns the trimmed string and does not modify its receiver.")
    @intrinsic(StringTrimAsciiWhitespace)
    fn trimAsciiWhitespace() -> String;

    /// Reports whether this string is empty or contains only Unicode whitespace.
    ///
    /// Whitespace follows the Unicode `White_Space` property. This includes
    /// ordinary ASCII spacing and line breaks as well as characters such as
    /// non-breaking space. [`String`] itself is never absent; use [`match`] on
    /// [`T?`] when [`None`] should also satisfy the condition.
    ///
    /// # Example
    ///
    /// Ignore a blank checkpoint label
    ///
    /// ```splitscript
    /// let padding = String.concat(["\t", '\u{00a0}' as String, "\n"])
    /// let missingLabel = padding.isBlank()
    /// ```
    @mustUse("The string blankness result must be used.")
    @intrinsic(StringIsBlank)
    fn isBlank() -> bool;

    /// Pads the beginning of this string to a minimum Unicode-scalar length.
    ///
    /// The original string is returned unchanged when it already contains at
    /// least `width` Unicode scalar values. Otherwise `fill` is repeated before
    /// it. This measures scalar values, not UTF-8 bytes or terminal columns.
    ///
    /// # Example
    ///
    /// Zero-pad a numeric identifier
    ///
    /// ```splitscript
    /// let identifier = "7".padStart(3, '0')
    /// ```
    @mustUse("Strings are immutable; padStart returns the padded string and does not modify its receiver.")
    @intrinsic(StringPadStart)
    fn padStart(
        /// The minimum number of Unicode scalar values in the result.
        width: u32,
        /// The character repeated before the original string.
        fill: char,
    ) -> String;

    /// Pads the end of this string to a minimum Unicode-scalar length.
    ///
    /// The original string is returned unchanged when it already contains at
    /// least `width` Unicode scalar values. Otherwise `fill` is repeated after
    /// it. This measures scalar values, not UTF-8 bytes or terminal columns.
    ///
    /// # Example
    ///
    /// Space-pad a diagnostic label
    ///
    /// ```splitscript
    /// let label = "Split".padEnd(9, ' ')
    /// ```
    @mustUse("Strings are immutable; padEnd returns the padded string and does not modify its receiver.")
    @intrinsic(StringPadEnd)
    fn padEnd(
        /// The minimum number of Unicode scalar values in the result.
        width: u32,
        /// The character repeated after the original string.
        fill: char,
    ) -> String;

    /// Replaces every exact, non-overlapping occurrence of a string.
    ///
    /// Matches are case-sensitive and selected from left to right. An empty
    /// search string returns an error because insertion between bytes would not
    /// preserve the UTF-8 string invariant. The result is allocated at its exact
    /// final byte length; an unrepresentable length also returns an error.
    ///
    /// # Example
    ///
    /// Normalize a scene-name separator
    ///
    /// ```splitscript
    /// let sceneName = "Forest_Complete"
    /// let label = sceneName.replaceAll("_", " ") else sceneName
    /// ```
    @mustUse("Strings are immutable; replaceAll returns a new string and does not modify its receiver.")
    @intrinsic(StringReplaceAll)
    fn replaceAll(
        /// The non-empty string to find.
        search: String,
        /// The string inserted for every match.
        replacement: String,
    ) -> String!;

    /// Splits this string at every exact, non-overlapping delimiter.
    ///
    /// Matching is case-sensitive over UTF-8 text. Empty segments before,
    /// between, and after delimiters are preserved. An empty delimiter returns
    /// an error rather than defining insertion points between UTF-8 bytes.
    ///
    /// # Example
    ///
    /// Parse a structured level identifier
    ///
    /// ```splitscript
    /// let parts = "01_02_0".split("_") else []
    /// let chapter = parts[0]
    /// ```
    @mustUse("Strings are immutable; split returns the resulting string array.")
    @intrinsic(StringSplit)
    fn split(
        /// The non-empty delimiter removed between segments.
        delimiter: String,
    ) -> [String]!;

    /// Parses this string as an inferred numeric type.
    ///
    /// Parsing consumes the entire string and accepts only ASCII decimal text;
    /// surrounding whitespace and digit separators are errors. Integers allow
    /// an optional sign and are checked against the exact target width. Floats
    /// additionally allow a decimal point and `e` or `E` exponent. `NaN`,
    /// `inf`, and `Infinity` are accepted case-insensitively. Finite overflow
    /// produces signed infinity and underflow produces signed zero.
    ///
    /// # Example
    ///
    /// Parse a percentage read from process memory
    ///
    /// ```splitscript
    /// let percentage: f64 = "87.5".parse() else 0.0
    /// ```
    ///
    /// # Example
    ///
    /// Parse a special floating-point value
    ///
    /// ```splitscript
    /// let positiveInfinity: f64 = "Infinity".parse() else 0.0
    /// ```
    @intrinsic(StringParse)
    fn parse<T: Numeric>() -> T!;

    /// Returns the raw UTF-8 byte at an offset.
    ///
    /// The index uses the same zero-based byte offsets as [`byteLength`] and
    /// [`slice`]. Every in-range byte is observable, including a continuation
    /// byte within a multibyte code point. An out-of-range index returns an
    /// error.
    ///
    /// # Example
    ///
    /// Inspect a fixed-format ASCII identifier
    ///
    /// ```splitscript
    /// let separator = "map_01".byteAt(3) else 0
    /// if separator == 0x5f {
    ///     print("Found the separator")
    /// }
    /// ```
    @intrinsic(StringByteAt)
    fn byteAt(
        /// The zero-based UTF-8 byte offset.
        byteIndex: u32,
    ) -> u8!;

    /// Returns the Unicode character beginning at a UTF-8 byte offset.
    ///
    /// The index uses the same zero-based byte offsets as [`byteLength`] and
    /// [`slice`], not JavaScript's UTF-16 code-unit indexes. The index must point
    /// to the first byte of a character. An out-of-range index or a
    /// continuation-byte index returns an error.
    ///
    /// # Example
    ///
    /// Inspect a non-ASCII character
    ///
    /// ```splitscript
    /// let sharpS = "Straße".charAt(4) else '\0'
    /// if sharpS == 'ß' {
    ///     print("Found sharp S")
    /// }
    /// ```
    @intrinsic(StringCharAt)
    fn charAt(
        /// The zero-based UTF-8 byte offset of the character's first byte.
        byteIndex: u32,
    ) -> char!;

    /// Extracts text between two UTF-8 byte offsets.
    ///
    /// The start index is inclusive and the end index is exclusive. Invalid,
    /// reversed, or out-of-range bounds return an error, as do offsets inside a
    /// multibyte code point. The result is newly allocated and can never contain
    /// more UTF-8 bytes than this string.
    ///
    /// # Example
    ///
    /// Extract a level-number component
    ///
    /// ```splitscript
    /// let prefix = "Straße".slice(0, 6) else "Unknown"
    /// ```
    @intrinsic(StringSlice)
    fn slice(
        /// The inclusive UTF-8 byte offset.
        start: u32,
        /// The exclusive UTF-8 byte offset.
        end: u32,
    ) -> String!;

    /// Concatenates an array of strings.
    ///
    /// A new WebAssembly GC string is allocated.
    ///
    /// # Example
    ///
    /// Join strings
    ///
    /// ```splitscript
    /// let label = String.concat(["Stage ", "Forest"])
    /// ```
    @intrinsic(StringConcat)
    static fn concat(
        /// The strings to concatenate in order.
        values: [String],
    ) -> String;

    /// Joins an array of strings with one separator between adjacent values.
    ///
    /// Empty and single-element arrays add no separators. The final string is
    /// allocated once after measuring every value and separator.
    ///
    /// # Example
    ///
    /// Format a route identifier
    ///
    /// ```splitscript
    /// let route = String.join(["chapter", "room", "exit"], ".")
    /// ```
    @mustUse("The joined string must be used.")
    @intrinsic(StringJoin)
    static fn join(
        /// The strings to join in order.
        values: [String],
        /// The string inserted between adjacent values.
        separator: String,
    ) -> String;
}

/// Provides whole-file, read-only filesystem operations.
///
/// These associated functions open, consume, and close a file within one call;
/// no file handle escapes into SplitScript. The WASI filesystem is otherwise
/// almost empty; the host filesystem is currently mounted read-only below
/// `/mnt`. Paths must be absolute because there is no portable current
/// directory. Other absolute roots may be exposed by the runtime in the future.
///
/// On Windows, `C:\foo\bar.txt` becomes `/mnt/c/foo/bar.txt` (and likewise
/// for other drive letters). On Linux or macOS, `/foo/bar.txt` becomes
/// `/mnt/foo/bar.txt`.
///
/// [`Process.path`] and [`Module.path`] already return this portable spelling.
///
/// # Example
///
/// Read a selected data file
///
/// ```splitscript
/// let bytes = File.readAllBytes("/mnt/c/Games/example/data.bin")?
/// print(`Loaded {bytes.length()} bytes`)
/// ```
@representation(scalar, i32)
@valueUsage()
intrinsic type File {
    /// Reads an entire file as raw bytes.
    ///
    /// The file is opened read-only and closed before this function returns.
    /// An empty file produces an empty array. Missing files, directories,
    /// inaccessible paths, and interrupted reads return an error. Repeated
    /// calls always consult the filesystem and are not cached.
    ///
    /// # Example
    ///
    /// Load a binary lookup table
    ///
    /// ```splitscript
    /// let table = File.readAllBytes("/mnt/c/Games/example/tables/rooms.bin")?
    /// ```
    @mustUse("The file contents or error must be used.")
    @intrinsic(FileReadAllBytes)
    static fn readAllBytes(
        /// Absolute path in the portable WASI namespace. The host filesystem is
        /// currently below `/mnt`: `C:\Games\data.bin` maps to
        /// `/mnt/c/Games/data.bin`, while `/opt/game/data.bin` maps to
        /// `/mnt/opt/game/data.bin`.
        path: String,
    ) -> [u8]!;

    /// Reads an entire UTF-8 text file.
    ///
    /// This is the text counterpart to [`File.readAllBytes`]. The bytes must
    /// contain valid UTF-8; malformed text returns an error rather than being
    /// replaced lossily. The result preserves a UTF-8 BOM, line endings, and
    /// embedded NUL bytes exactly as text.
    ///
    /// # Example
    ///
    /// Load configuration text
    ///
    /// ```splitscript
    /// let configuration = File.readAllText("/mnt/home/player/game/configuration.json")?
    /// ```
    @mustUse("The file text or error must be used.")
    @intrinsic(FileReadAllText)
    static fn readAllText(
        /// Absolute path in the portable WASI namespace. The host filesystem is
        /// currently below `/mnt`: `C:\Games\config.json` maps to
        /// `/mnt/c/Games/config.json`, while `/home/player/config.json` maps to
        /// `/mnt/home/player/config.json`.
        path: String,
    ) -> String!;
}

/// Stores a compiled process-memory signature.
///
/// Signature values are created by signature literals and consumed by scanning operations.
///
/// # Example
///
/// Scan for a machine-code marker
///
/// ```splitscript
/// let executable = await process.mainModule()
/// let markerAddress = await executable.scan(sig"48 8B ?? 89")
/// ```
@representation(scalar, i64)
@valueUsage(structField, enumPayload, localVariable, globalVariable)
intrinsic type Signature {}

/// Identifies a signature selected by a multi-pattern memory scan.
///
/// The address and input index are returned together so one scan can both find
/// a marker and identify the matching executable layout.
///
/// # Example
///
/// Select a discovered memory layout
///
/// ```splitscript
/// let found = await process.scanMemoryAny([sig"48 8B ??", sig"48 89 ??"])
/// print(found.index)
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, localVariable, globalVariable)
struct SignatureMatch {
    /// Address where the signature matched.
    ///
    /// This is the first byte corresponding to the selected signature. Use the
    /// companion [`index`](field@SignatureMatch.index) field to determine which
    /// input pattern produced it.
    ///
    /// # Example
    ///
    /// Read the matching address
    ///
    /// ```splitscript
    /// let found = await process.scanMemoryAny([sig"48 8B ??"])
    /// let marker = found.address
    /// ```
    address: address,
    /// Zero-based index in the supplied signature array.
    ///
    /// The index preserves the order passed to [`Process.scanMemoryAny`], so it
    /// can select a layout or interpretation without rescanning the process.
    ///
    /// # Example
    ///
    /// Select the associated layout
    ///
    /// ```splitscript
    /// let found = await process.scanMemoryAny([sig"48 8B ??"])
    /// let layoutIndex = found.index
    /// ```
    index: u32,
}

/// Represents a precise span of time.
///
/// Durations carry normalized whole seconds and nanoseconds and are used for
/// timer game time. The nanosecond component is always between zero and
/// 999,999,999, including for negative durations.
///
/// # Example
///
/// Represent an exact delay
///
/// ```splitscript
/// let delay = Duration.fromSeconds(2)
/// ```
@representation(gcStruct)
@valueUsage(structField, enumPayload, stateField, localVariable, globalVariable)
@capabilities(Equatable)
struct Duration {
    /// Stores the whole-second component.
    private seconds: i64,

    /// Stores the fractional nanosecond component.
    private nanoseconds: i32,

    /// Constructs a zero-length duration.
    ///
    /// This is the neutral value for accumulated game time.
    ///
    /// # Example
    ///
    /// Initialize accumulated time
    ///
    /// ```splitscript
    /// let accumulated = Duration.zero()
    /// ```
    static fn zero() -> Duration {
        return Duration.fromParts(0, 0)
    }

    /// Constructs a duration from seconds.
    ///
    /// Every integer and floating-point type is accepted. Integer inputs use
    /// an exact conversion without passing through floating point; fractional
    /// inputs retain nanosecond precision.
    ///
    /// # Example
    ///
    /// Convert an integer counter to game time
    ///
    /// ```splitscript
    /// let elapsed = Duration.fromSeconds(125)
    /// ```
    static fn fromSeconds<T: Integer>(
        /// The number of elapsed seconds.
        seconds: T,
    ) -> Duration {
        if seconds < 0 {
            return Duration.fromParts(seconds as i64, 0)
        }
        let unsigned = seconds as u64
        if unsigned > 9_223_372_036_854_775_807 {
            return Duration.fromParts(9_223_372_036_854_775_807, 999_999_999)
        }
        return Duration.fromParts(unsigned as i64, 0)
    }

    static fn fromSeconds<T: Float>(
        /// The number of elapsed seconds.
        seconds: T,
    ) -> Duration {
        let integralSeconds = seconds.floor()
        let wholeSeconds = integralSeconds as i64
        let nanoseconds = ((seconds - integralSeconds) * 1_000_000_000) as i32
        return Duration.fromParts(wholeSeconds, nanoseconds)
    }

    /// Constructs a duration from milliseconds.
    ///
    /// Every integer and floating-point type is accepted. Integer inputs are
    /// converted exactly, including negative values; floating-point inputs may
    /// include fractional milliseconds and are converted through
    /// [`fromSeconds`]. When porting C#, this is the direct replacement for
    /// `TimeSpan.FromMilliseconds`.
    ///
    /// # Example
    ///
    /// Convert milliseconds to game time
    ///
    /// ```splitscript
    /// let elapsed = Duration.fromMilliseconds(1_250)
    /// ```
    static fn fromMilliseconds<T: Integer>(
        /// The number of elapsed milliseconds.
        milliseconds: T,
    ) -> Duration {
        if milliseconds < 0 {
            let signed = milliseconds as i64
            return Duration.fromParts(
                signed / 1_000,
                ((signed % 1_000) * 1_000_000) as i32,
            )
        }
        let unsigned = milliseconds as u64
        return Duration.fromParts(
            (unsigned / 1_000) as i64,
            ((unsigned % 1_000) * 1_000_000) as i32,
        )
    }

    static fn fromMilliseconds<T: Float>(
        /// The number of elapsed milliseconds.
        milliseconds: T,
    ) -> Duration {
        return Duration.fromSeconds(milliseconds / 1_000)
    }

    /// Constructs a duration from minutes.
    ///
    /// Every integer and floating-point type is accepted. Integer inputs are
    /// scaled exactly and saturate only when the duration representation cannot
    /// contain the result.
    ///
    /// # Example
    ///
    /// Convert a route timer measured in minutes
    ///
    /// ```splitscript
    /// let elapsed = Duration.fromMinutes(2.5)
    /// ```
    static fn fromMinutes<T: Integer>(
        /// The number of elapsed minutes.
        minutes: T,
    ) -> Duration {
        let signed = minutes as i64
        if minutes < 0 {
            if signed > 153_722_867_280_912_930 {
                return Duration.fromParts(9_223_372_036_854_775_807, 999_999_999)
            }
            if signed < -153_722_867_280_912_930 {
                return Duration.fromParts(-9_223_372_036_854_775_807 - 1, 0)
            }
            return Duration.fromParts(signed * 60, 0)
        }
        let unsigned = minutes as u64
        if unsigned > 153_722_867_280_912_930 {
            return Duration.fromParts(9_223_372_036_854_775_807, 999_999_999)
        }
        return Duration.fromParts((unsigned as i64) * 60, 0)
    }

    static fn fromMinutes<T: Float>(
        /// The number of elapsed minutes.
        minutes: T,
    ) -> Duration {
        return Duration.fromSeconds(minutes * 60)
    }

    /// Constructs a duration from hours.
    ///
    /// Every integer and floating-point type is accepted.
    ///
    /// # Example
    ///
    /// Construct a one-hour timeout
    ///
    /// ```splitscript
    /// let timeout = Duration.fromHours(1.0)
    /// ```
    static fn fromHours<T: Integer>(
        /// The number of elapsed hours.
        hours: T,
    ) -> Duration {
        let signed = hours as i64
        if hours < 0 {
            if signed > 2_562_047_788_015_215 {
                return Duration.fromParts(9_223_372_036_854_775_807, 999_999_999)
            }
            if signed < -2_562_047_788_015_215 {
                return Duration.fromParts(-9_223_372_036_854_775_807 - 1, 0)
            }
            return Duration.fromParts(signed * 3_600, 0)
        }
        let unsigned = hours as u64
        if unsigned > 2_562_047_788_015_215 {
            return Duration.fromParts(9_223_372_036_854_775_807, 999_999_999)
        }
        return Duration.fromParts((unsigned as i64) * 3_600, 0)
    }

    static fn fromHours<T: Float>(
        /// The number of elapsed hours.
        hours: T,
    ) -> Duration {
        return Duration.fromSeconds(hours * 3_600)
    }

    /// Constructs a duration from days.
    ///
    /// Every integer and floating-point type is accepted. A day is exactly
    /// 86,400 seconds; calendar and time-zone rules are intentionally not
    /// involved.
    ///
    /// # Example
    ///
    /// Construct a multi-day sentinel
    ///
    /// ```splitscript
    /// let sentinel = Duration.fromDays(2.0)
    /// ```
    static fn fromDays<T: Integer>(
        /// The number of elapsed 24-hour days.
        days: T,
    ) -> Duration {
        let signed = days as i64
        if days < 0 {
            if signed > 106_751_991_167_300 {
                return Duration.fromParts(9_223_372_036_854_775_807, 999_999_999)
            }
            if signed < -106_751_991_167_300 {
                return Duration.fromParts(-9_223_372_036_854_775_807 - 1, 0)
            }
            return Duration.fromParts(signed * 86_400, 0)
        }
        let unsigned = days as u64
        if unsigned > 106_751_991_167_300 {
            return Duration.fromParts(9_223_372_036_854_775_807, 999_999_999)
        }
        return Duration.fromParts((unsigned as i64) * 86_400, 0)
    }

    static fn fromDays<T: Float>(
        /// The number of elapsed 24-hour days.
        days: T,
    ) -> Duration {
        return Duration.fromSeconds(days * 86_400)
    }

    /// Constructs a duration from nanoseconds.
    ///
    /// Every integer and floating-point type is accepted. Integer inputs retain
    /// their exact value; floating-point inputs may include sub-nanosecond data,
    /// which is truncated to the duration's nanosecond resolution.
    ///
    /// # Example
    ///
    /// Convert an exact nanosecond counter
    ///
    /// ```splitscript
    /// let elapsed = Duration.fromNanoseconds(1_250_000_000)
    /// ```
    static fn fromNanoseconds<T: Integer>(
        /// The number of elapsed nanoseconds.
        nanoseconds: T,
    ) -> Duration {
        if nanoseconds < 0 {
            let signed = nanoseconds as i64
            return Duration.fromParts(
                signed / 1_000_000_000,
                (signed % 1_000_000_000) as i32,
            )
        }
        let unsigned = nanoseconds as u64
        return Duration.fromParts(
            (unsigned / 1_000_000_000) as i64,
            (unsigned % 1_000_000_000) as i32,
        )
    }

    static fn fromNanoseconds<T: Float>(
        /// The number of elapsed nanoseconds.
        nanoseconds: T,
    ) -> Duration {
        return Duration.fromSeconds(nanoseconds / 1_000_000_000)
    }

    /// Constructs a duration from frames.
    ///
    /// Every integer type is accepted. The frame count and rate use the same
    /// inferred type, so ordinary integer literals adopt the counter's type.
    /// Whole seconds are converted exactly; only the subsecond remainder passes
    /// through floating point to avoid overflowing narrow and 64-bit counters.
    ///
    /// # Example
    ///
    /// Convert frames to game time
    ///
    /// ```splitscript
    /// let elapsed = Duration.fromFrames(150, 60)
    /// ```
    static fn fromFrames<T: Integer>(
        /// The elapsed frame count.
        frames: T,
        /// The frame rate.
        framesPerSecond: T,
    ) -> Duration {
        let wholeFrames = frames / framesPerSecond
        let remainingFrames = frames % framesPerSecond
        let whole = Duration.fromSeconds(wholeFrames)
        if remainingFrames == 0 {
            return whole
        }
        if whole.seconds == 9_223_372_036_854_775_807
            || whole.seconds == -9_223_372_036_854_775_807 - 1
        {
            return whole
        }
        let fractional = Duration.fromSeconds(
            remainingFrames as f64 / framesPerSecond as f64,
        )
        return whole + fractional
    }

    /// Constructs a duration from seconds and nanoseconds.
    ///
    /// The two components become the runtime duration representation.
    ///
    /// # Example
    ///
    /// Construct an exact duration
    ///
    /// ```splitscript
    /// let elapsed = Duration.fromParts(12, 500_000_000)
    /// ```
    static fn fromParts(
        /// Whole seconds.
        seconds: i64,
        /// The fractional nanoseconds.
        nanoseconds: i32,
    ) -> Duration {
        let normalizedSeconds = seconds + (nanoseconds / 1_000_000_000) as i64
        let normalizedNanoseconds = nanoseconds % 1_000_000_000
        if normalizedNanoseconds < 0 {
            return Duration {
                seconds: normalizedSeconds - 1,
                nanoseconds: normalizedNanoseconds + 1_000_000_000,
            }
        }
        return Duration {
            seconds: normalizedSeconds,
            nanoseconds: normalizedNanoseconds,
        }
    }

    /// Returns the normalized whole-second component.
    ///
    /// For negative fractional durations this is the mathematical floor. For
    /// example, negative 1.25 seconds has a whole-second component of -2.
    ///
    /// # Example
    ///
    /// Inspect an exact duration
    ///
    /// ```splitscript
    /// let seconds = Duration.fromSeconds(12.5).wholeSeconds()
    /// ```
    fn wholeSeconds() -> i64 {
        return self.seconds
    }

    /// Returns the normalized subsecond nanosecond component.
    ///
    /// The result is always between zero and 999,999,999.
    ///
    /// # Example
    ///
    /// Inspect subsecond precision
    ///
    /// ```splitscript
    /// let nanoseconds = Duration.fromSeconds(12.5).subsecondNanoseconds()
    /// ```
    fn subsecondNanoseconds() -> i32 {
        return self.nanoseconds
    }

    /// Returns the complete duration as floating-point seconds.
    ///
    /// The f64 result preserves nanosecond precision for ordinary autosplitter
    /// time spans but may round extremely large durations.
    ///
    /// # Example
    ///
    /// Compare elapsed time in seconds
    ///
    /// ```splitscript
    /// if Duration.fromMilliseconds(750.0).totalSeconds() >= 0.5 {
    ///     print("ready")
    /// }
    /// ```
    fn totalSeconds() -> f64 {
        return self.seconds as f64 + self.nanoseconds as f64 / 1_000_000_000
    }

    /// Returns the complete duration as floating-point milliseconds.
    ///
    /// The f64 result may round extremely large durations.
    ///
    /// # Example
    ///
    /// Measure a debounce interval
    ///
    /// ```splitscript
    /// if Duration.fromMilliseconds(300.0).totalMilliseconds() >= 250 {
    ///     print("ready")
    /// }
    /// ```
    fn totalMilliseconds() -> f64 {
        return self.seconds as f64 * 1_000 + self.nanoseconds as f64 / 1_000_000
    }

    /// Adds another duration and normalizes the result.
    ///
    /// The returned nanosecond component preserves the Duration invariant.
    ///
    /// # Example
    ///
    /// Accumulate two measured intervals
    ///
    /// ```splitscript
    /// let first = Duration.fromMilliseconds(250.0)
    /// let second = Duration.fromMilliseconds(500.0)
    /// let total = first.add(second)
    /// ```
    @operator(add)
    fn add(
        /// The duration to add.
        other: Duration,
    ) -> Duration {
        return Duration.fromParts(
            self.seconds + other.seconds,
            self.nanoseconds + other.nanoseconds
        )
    }

    /// Subtracts another duration and normalizes the result.
    ///
    /// Negative results retain their full subsecond precision.
    ///
    /// # Example
    ///
    /// Measure the difference between two durations
    ///
    /// ```splitscript
    /// let currentTime = Duration.fromSeconds(5.0)
    /// let previousTime = Duration.fromSeconds(3.0)
    /// let difference = currentTime.subtract(previousTime)
    /// ```
    @operator(subtract)
    fn subtract(
        /// The duration to subtract.
        other: Duration,
    ) -> Duration {
        return Duration.fromParts(
            self.seconds - other.seconds,
            self.nanoseconds - other.nanoseconds
        )
    }

    /// Reports whether this duration is shorter than another duration.
    ///
    /// This method implements the [`<`](operator@Duration.lessThan) operator
    /// using the normalized whole and fractional components without converting
    /// to floating point.
    ///
    /// # Example
    ///
    /// Check whether a delay is still pending
    ///
    /// ```splitscript
    /// let elapsed = Duration.fromMilliseconds(200.0)
    /// let delay = Duration.fromMilliseconds(250.0)
    /// let pending = elapsed < delay
    /// ```
    @operator(lessThan)
    fn lessThan(
        /// The duration to compare against.
        other: Duration,
    ) -> bool {
        return self.seconds < other.seconds
            || self.seconds == other.seconds && self.nanoseconds < other.nanoseconds
    }

    /// Reports whether this duration is no longer than another duration.
    ///
    /// This method implements the [`<=`](operator@Duration.lessThanOrEqual)
    /// operator without converting to floating point.
    ///
    /// # Example
    ///
    /// Accept a duration at an inclusive limit
    ///
    /// ```splitscript
    /// let elapsed = Duration.fromMilliseconds(250.0)
    /// let limit = Duration.fromMilliseconds(250.0)
    /// let accepted = elapsed <= limit
    /// ```
    @operator(lessThanOrEqual)
    fn lessThanOrEqual(
        /// The duration to compare against.
        other: Duration,
    ) -> bool {
        return !self.greaterThan(other)
    }

    /// Reports whether this duration is longer than another duration.
    ///
    /// This method implements the [`>`](operator@Duration.greaterThan) operator
    /// using the normalized whole and fractional components without converting
    /// to floating point.
    ///
    /// # Example
    ///
    /// Check whether a delayed split is ready
    ///
    /// ```splitscript
    /// let elapsed = Duration.fromMilliseconds(300.0)
    /// let delay = Duration.fromMilliseconds(250.0)
    /// let ready = elapsed > delay
    /// ```
    @operator(greaterThan)
    fn greaterThan(
        /// The duration to compare against.
        other: Duration,
    ) -> bool {
        return self.seconds > other.seconds
            || self.seconds == other.seconds && self.nanoseconds > other.nanoseconds
    }

    /// Reports whether this duration is at least another duration.
    ///
    /// This method implements the [`>=`](operator@Duration.greaterThanOrEqual)
    /// operator without converting to floating point.
    ///
    /// # Example
    ///
    /// Trigger once a delay has elapsed
    ///
    /// ```splitscript
    /// let elapsed = Duration.fromMilliseconds(250.0)
    /// let delay = Duration.fromMilliseconds(250.0)
    /// let ready = elapsed >= delay
    /// ```
    @operator(greaterThanOrEqual)
    fn greaterThanOrEqual(
        /// The duration to compare against.
        other: Duration,
    ) -> bool {
        return !self.lessThan(other)
    }
}

/// Identifies one reading of the runtime's monotonic clock.
///
/// Instants are suitable for elapsed-time measurements such as delayed splits
/// and debouncing. They are unrelated to calendar time and have no meaningful
/// absolute value.
///
/// # Example
///
/// Capture a monotonic timestamp
///
/// ```splitscript
/// let detectedAt: Instant = Instant.now()
/// ```
@representation(gcStruct)
@valueUsage(structField, enumPayload, localVariable, globalVariable)
@capabilities(Equatable)
struct Instant {
    /// Stores the opaque monotonic timestamp in nanoseconds.
    private nanoseconds: i64,

    /// Reads the runtime's monotonic clock.
    ///
    /// Successive readings never move backwards while one runtime instance is
    /// active. The absolute value is intentionally not exposed.
    ///
    /// # Example
    ///
    /// Remember when an event occurred
    ///
    /// ```splitscript
    /// let detectedAt = Instant.now()
    /// ```
    @intrinsic(InstantNow)
    static fn now() -> Instant;

    /// Offsets this instant by a duration.
    ///
    /// This method implements [`Instant.add`]. Results before the
    /// monotonic clock's zero point clamp to zero, and results beyond the
    /// largest representable instant clamp to that maximum. The calculation
    /// preserves nanosecond precision and does not wrap.
    ///
    /// # Example
    ///
    /// Calculate a deadline
    ///
    /// ```splitscript
    /// let startedAt = Instant.now()
    /// let deadline = startedAt + Duration.fromMilliseconds(250.0)
    /// ```
    @mustUse("Instants are immutable; add returns the offset instant and does not modify its receiver.")
    @operator(add)
    fn add(
        /// The signed duration by which to offset the instant.
        duration: Duration,
    ) -> Instant {
        let currentSeconds = self.nanoseconds / 1_000_000_000
        let currentNanoseconds = self.nanoseconds % 1_000_000_000
        let durationSeconds = duration.wholeSeconds()

        if durationSeconds < 0 - currentSeconds - 1 {
            return Instant { nanoseconds: 0 }
        }
        if durationSeconds > 9_223_372_036 - currentSeconds {
            return Instant { nanoseconds: 9_223_372_036_854_775_807 }
        }

        let combinedNanoseconds = currentNanoseconds
            + duration.subsecondNanoseconds() as i64
        let resultSeconds = currentSeconds + durationSeconds
            + combinedNanoseconds / 1_000_000_000
        let resultNanoseconds = combinedNanoseconds % 1_000_000_000

        if resultSeconds < 0 {
            return Instant { nanoseconds: 0 }
        }
        if resultSeconds > 9_223_372_036
            || resultSeconds == 9_223_372_036
                && resultNanoseconds > 854_775_807
        {
            return Instant { nanoseconds: 9_223_372_036_854_775_807 }
        }
        return Instant {
            nanoseconds: resultSeconds * 1_000_000_000 + resultNanoseconds,
        }
    }

    /// Returns the elapsed duration since an earlier instant.
    ///
    /// The result is zero when `earlier` is later than the receiver, matching
    /// the saturating behavior expected for polling and debounce logic.
    ///
    /// # Example
    ///
    /// Measure between two clock readings
    ///
    /// ```splitscript
    /// let startedAt = Instant.now()
    /// let finishedAt = Instant.now()
    /// let elapsed = finishedAt.durationSince(startedAt)
    /// ```
    fn durationSince(
        /// The earlier monotonic clock reading.
        earlier: Instant,
    ) -> Duration {
        if self.nanoseconds <= earlier.nanoseconds {
            return Duration.zero()
        }
        return Duration.fromNanoseconds(self.nanoseconds - earlier.nanoseconds)
    }

    /// Returns the duration elapsed since this instant.
    ///
    /// This is shorthand for reading the clock and calling [`durationSince`].
    ///
    /// # Example
    ///
    /// Trigger after a debounce interval
    ///
    /// ```splitscript
    /// let detectedAt = Instant.now()
    /// if detectedAt.elapsed().totalMilliseconds() >= 250 {
    ///     print("ready")
    /// }
    /// ```
    fn elapsed() -> Duration {
        return Instant.now().durationSince(self)
    }

    /// Reports whether at least the requested duration has elapsed.
    ///
    /// This is the usual operation for delayed splits and debouncing. It reads
    /// the monotonic clock once and compares exact durations.
    ///
    /// # Example
    ///
    /// Wait for a delayed split
    ///
    /// ```splitscript
    /// let detectedAt = Instant.now()
    /// let ready = detectedAt.hasElapsed(Duration.fromMilliseconds(250.0))
    /// ```
    fn hasElapsed(
        /// The minimum duration that must have elapsed.
        delay: Duration,
    ) -> bool {
        return self.elapsed() >= delay
    }
}

/// Describes the native pointer width used by a process module.
///
/// Pointer width controls how deep pointer paths decode intermediate addresses.
///
/// # Example
///
/// Select a 64-bit pointer layout
///
/// ```splitscript
/// let pointerWidth = PointerSize.Bit64
/// ```
@representation(enum, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable, globalVariable)
@capabilities(Equatable)
enum PointerSize {
    /// Intermediate pointers contain 32-bit addresses.
    ///
    /// # Example
    ///
    /// Select 32-bit pointer decoding
    ///
    /// ```splitscript
    /// let pointerWidth = PointerSize.Bit32
    /// ```
    Bit32,

    /// Intermediate pointers contain 64-bit addresses.
    ///
    /// # Example
    ///
    /// Select 64-bit pointer decoding explicitly
    ///
    /// ```splitscript
    /// let nativeWidth = PointerSize.Bit64
    /// ```
    Bit64,
}

/// Selects the permissions required by a mapped-memory query.
///
/// The query may return ranges with additional permissions.
///
/// # Example
///
/// Require readable and writable memory
///
/// ```splitscript
/// let requiredAccess = MemoryRangeAccess.ReadWrite
/// ```
@representation(enum, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable, globalVariable)
@capabilities(Equatable)
enum MemoryRangeAccess {
    /// Requires readable memory.
    ///
    /// # Example
    ///
    /// Request readable memory
    ///
    /// ```splitscript
    /// let access = MemoryRangeAccess.Read
    /// ```
    Read,

    /// Requires readable and writable memory.
    ///
    /// # Example
    ///
    /// Request mutable emulated memory
    ///
    /// ```splitscript
    /// let access = MemoryRangeAccess.ReadWrite
    /// ```
    ReadWrite,

    /// Requires readable and executable memory.
    ///
    /// # Example
    ///
    /// Request executable code memory
    ///
    /// ```splitscript
    /// let access = MemoryRangeAccess.ReadExecute
    /// ```
    ReadExecute,
}

/// Describes one mapped process-memory range.
///
/// Values are snapshots of host mapping metadata discovered cooperatively.
///
/// # Example
///
/// Inspect a discovered mapping
///
/// ```splitscript
/// let emulatorRange = await process.findMemoryRange(0x48000, MemoryRangeAccess.ReadWrite)
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable, globalVariable)
struct MemoryRange {
    /// Returns the first mapped address.
    ///
    /// # Example
    ///
    /// Read the mapping base
    ///
    /// ```splitscript
    /// let range = await process.findMemoryRange(0x48000, MemoryRangeAccess.ReadWrite)
    /// let base = range.address
    /// ```
    address: address,

    /// Returns the mapped byte length.
    ///
    /// # Example
    ///
    /// Read the mapping size
    ///
    /// ```splitscript
    /// let range = await process.findMemoryRange(0x48000, MemoryRangeAccess.ReadWrite)
    /// let bytes = range.size
    /// ```
    size: u64,

    /// Reports whether the range is readable.
    ///
    /// # Example
    ///
    /// Inspect read access
    ///
    /// ```splitscript
    /// let range = await process.findMemoryRange(0x48000, MemoryRangeAccess.ReadWrite)
    /// let canRead = range.readable
    /// ```
    readable: bool,

    /// Reports whether the range is writable.
    ///
    /// # Example
    ///
    /// Inspect write access
    ///
    /// ```splitscript
    /// let range = await process.findMemoryRange(0x48000, MemoryRangeAccess.ReadWrite)
    /// let canWrite = range.writable
    /// ```
    writable: bool,

    /// Reports whether the range is executable.
    ///
    /// # Example
    ///
    /// Inspect execute access
    ///
    /// ```splitscript
    /// let range = await process.findMemoryRange(0x48000, MemoryRangeAccess.ReadWrite)
    /// let canExecute = range.executable
    /// ```
    executable: bool,
}

/// Describes a native pointer chain rooted at an address.
///
/// A path keeps version-specific pointer data separate from state polling and
/// resolves every intermediate pointer according to the attached executable's
/// automatically detected width.
///
/// # Example
///
/// Build a reusable pointer path
///
/// ```splitscript
/// let healthPath = 0x1000.memoryPath([0x20, 0x18], 0x8)
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable, globalVariable)
struct MemoryPath {
    /// Returns the address at which traversal starts.
    ///
    /// # Example
    ///
    /// Inspect a path's starting address
    ///
    /// ```splitscript
    /// let path = 0x1000.memoryPath([0x20], 0x8)
    /// let start = path.base
    /// ```
    base: address,

    /// Returns the signed offsets that each end in an intermediate pointer read.
    ///
    /// # Example
    ///
    /// Inspect intermediate dereferences
    ///
    /// ```splitscript
    /// let path = 0x2000.memoryPath([0x30, 0x10], 0x4)
    /// let offsets = path.dereferences
    /// ```
    dereferences: [i64],

    /// Returns the signed offset applied after the final pointer read.
    ///
    /// # Example
    ///
    /// Inspect a path's final offset
    ///
    /// ```splitscript
    /// let path = 0x3000.memoryPath([], 0x14)
    /// let trailingOffset = path.finalOffset
    /// ```
    finalOffset: i64,

    /// Appends one pointer dereference and a new final offset.
    ///
    /// The current final offset becomes the address of the next native pointer
    /// read. The supplied offset is then applied to that pointer without
    /// another read. The original immutable path is not changed.
    ///
    /// # Example
    ///
    /// Follow a singleton to one of its fields
    ///
    /// ```splitscript
    /// let singleton = 0x1000.memoryPath([], 0x20)
    /// let health = singleton.dereference(0x18)
    /// ```
    @mustUse("Pointer paths are immutable; dereference returns an extended path.")
    fn dereference(
        /// Signed final offset to apply after reading the current path's pointer.
        offset: i64,
    ) -> MemoryPath {
        let dereferences: [i64] = []
        dereferences.extend(self.dereferences)
        dereferences.push(self.finalOffset)
        return MemoryPath {
            base: self.base,
            dereferences,
            finalOffset: offset,
        }
    }

    /// Resolves the path against the attached process.
    ///
    /// Failed and null intermediate pointer reads propagate as a [`T!`] error.
    ///
    /// # Example
    ///
    /// Resolve a discovered path
    ///
    /// ```splitscript
    /// let health = 0x1000.memoryPath([0x20], 0x18)
    /// let healthAddress = health.resolve() else return
    /// ```
    fn resolve() -> address! {
        let current = process.follow(self.base, self.dereferences)?
        return Ok(current.offset(self.finalOffset))
    }
}

/// A four-part numeric Windows executable version.
///
/// The components correspond to `major.minor.build.private` in a PE
/// `VS_FIXEDFILEINFO` resource. Keeping the parts typed avoids depending on
/// the inconsistent punctuation of legacy `FileVersionInfo` strings.
///
/// # Example
///
/// Compare a discovered version to a literal
///
/// ```splitscript
/// let supported = v"1.2.3.4" == v"1.2.3.4"
/// ```
///
/// Select behavior for a known build
///
/// ```splitscript
/// let label = match v"1.2.3.4" {
///     v"1.2.3.4" => "supported",
///     _ => "unknown",
/// }
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable, globalVariable)
@capabilities(Debug, Equatable, Display)
struct FileVersion {
    /// Major version component.
    ///
    /// # Example
    ///
    /// Read the major version
    ///
    /// ```splitscript
    /// let majorVersion = v"2.5.1.0".major
    /// ```
    major: u16,

    /// Minor version component.
    ///
    /// # Example
    ///
    /// Read the minor version
    ///
    /// ```splitscript
    /// let minorVersion = v"2.5.1.0".minor
    /// ```
    minor: u16,

    /// Build version component.
    ///
    /// # Example
    ///
    /// Read the build version
    ///
    /// ```splitscript
    /// let buildVersion = v"2.5.1.0".build
    /// ```
    build: u16,

    /// Private version component.
    ///
    /// # Example
    ///
    /// Read the private version
    ///
    /// ```splitscript
    /// let privateVersion = v"2.5.1.7".privatePart
    /// ```
    privatePart: u16,

    /// Constructs a numeric Windows file version from its four components.
    ///
    /// The [`v`] literal is the concise spelling for calls with constant
    /// components.
    ///
    /// # Example
    ///
    /// Construct a dynamically discovered version
    ///
    /// ```splitscript
    /// let version = FileVersion.fromParts(1, 2, 3, 4)
    /// ```
    static fn fromParts(
        /// Major version component.
        major: u16,
        /// Minor version component.
        minor: u16,
        /// Build version component.
        build: u16,
        /// Private version component.
        privatePart: u16,
    ) -> FileVersion {
        return FileVersion {
            major,
            minor,
            build,
            privatePart,
        }
    }

    /// Formats the version as `major.minor.build.private`.
    ///
    /// This is the standard-library implementation of [`Display`], so casts,
    /// interpolation, [`print`], and [`setVariable`] all use the same spelling.
    ///
    /// # Example
    ///
    /// Format a discovered executable version explicitly
    ///
    /// ```splitscript
    /// let text = v"1.2.3.4".toString()
    /// ```
    @display
    fn toString() -> String {
        return `{self.major}.{self.minor}.{self.build}.{self.privatePart}`
    }
}

/// The fixed numeric versions embedded in a Windows PE module.
///
/// Windows keeps separate file and product identities in `VS_FIXEDFILEINFO`.
/// They are often equal, but launchers and repackaged executables can use a
/// stable product version while changing the individual file version.
///
/// # Example
///
/// Compare file and product identities
///
/// ```splitscript
/// let executable = await process.mainModule()
/// let versions = executable.versionInfo() else return
/// let sameRelease = versions.file == versions.product
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, localVariable)
struct ModuleVersionInfo {
    /// The version of this particular executable or library file.
    ///
    /// # Example
    ///
    /// Read the file identity
    ///
    /// ```splitscript
    /// let executable = await process.mainModule()
    /// let versions = executable.versionInfo() else return
    /// let fileVersion = versions.file
    /// ```
    file: FileVersion,

    /// The version of the product to which the module belongs.
    ///
    /// # Example
    ///
    /// Read the product identity
    ///
    /// ```splitscript
    /// let executable = await process.mainModule()
    /// let versions = executable.versionInfo() else return
    /// let productVersion = versions.product
    /// ```
    product: FileVersion,
}

/// Describes a module loaded in the attached process.
///
/// A module exposes its base address and mapped size for bounded memory discovery.
///
/// # Example
///
/// Discover the main executable module
///
/// ```splitscript
/// let executable: Module = await process.mainModule()
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable)
struct Module {
    /// Returns the module base address.
    ///
    /// Relative virtual addresses within the image are measured from this
    /// value. Prefer [`offset`] when deriving another address so the intent is
    /// explicit at the call site.
    ///
    /// # Example
    ///
    /// Read a discovered module's base address
    ///
    /// ```splitscript
    /// let executable = await process.mainModule()
    /// let baseAddress = executable.address
    /// ```
    address: address,

    /// Returns the mapped module size.
    ///
    /// The value is the host-reported extent of the loaded image in bytes. It
    /// can be paired with [`address`] to constrain scanning or validate a
    /// relative offset before reading memory.
    ///
    /// # Example
    ///
    /// Read a discovered module's mapped size
    ///
    /// ```splitscript
    /// let executable = await process.mainModule()
    /// let mappedBytes = executable.size
    /// ```
    size: u64,

    /// The host module identity used for metadata queries.
    private name: String,

    private fn peOptionalHeader() -> address! {
        if process.read<u16>(self.address)? != 0x5a4d {
            throw "module does not have a DOS header"
        }

        let peOffset = process.read<u32>(self.address.add(0x3c))?
        let peHeader = self.address.add(peOffset as u64)
        if process.read<u32>(peHeader)? != 0x00004550 {
            throw "module does not have a PE header"
        }
        return Ok(peHeader.add(0x18))
    }

    /// Returns the module's host-provided filesystem path.
    ///
    /// The returned value is an absolute path in the runtime's portable,
    /// read-only filesystem namespace. Windows paths map by drive, so
    /// `C:\Games\engine.dll` becomes `/mnt/c/Games/engine.dll`. Linux and
    /// macOS paths gain the `/mnt` prefix, so `/opt/game/engine.so` becomes
    /// `/mnt/opt/game/engine.so`. It can be passed directly to
    /// [`File.readAllBytes`] or [`File.readAllText`].
    ///
    /// # Example
    ///
    /// Inspect the executable path
    ///
    /// ```splitscript
    /// let executable = await process.mainModule()
    /// let path = executable.path() else "Unknown"
    /// ```
    @requires(attachedProcess)
    @intrinsic(ModulePath)
    fn path() -> String!;

    /// Computes the MD5 fingerprint of the module's complete on-disk file.
    ///
    /// The result is the canonical 32-character uppercase hexadecimal form.
    /// This is intentionally based on file bytes rather than the mapped image,
    /// [`Module.size`], or version metadata, so builds with otherwise identical
    /// metadata can still be selected exactly. Hashing is cooperative: only a
    /// bounded file window is read per host update. If the file changes while
    /// it is being read, hashing restarts and only completes after observing
    /// one stable version. Filesystem and metadata failures are returned as an
    /// error.
    ///
    /// # Example
    ///
    /// Select a known executable build
    ///
    /// ```splitscript
    /// let executable = await process.mainModule()
    /// let fingerprint = (await executable.md5())?
    /// if fingerprint == "951389C953020FC7B5DEF32E7BED129A" {
    ///     print("recognized build")
    /// }
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(ModuleMd5)
    fn md5() -> async String!;

    /// Reads both fixed numeric versions from a Windows PE version resource.
    ///
    /// The parser validates the DOS and PE headers, follows the bounded
    /// resource-directory hierarchy, and verifies `VS_FIXEDFILEINFO` before
    /// returning the file and product components. Missing resources, malformed
    /// images, and failed memory reads are ordinary errors. Use this method
    /// when both identities are needed so the resource is traversed only once.
    ///
    /// # Example
    ///
    /// Inspect both identities
    ///
    /// ```splitscript
    /// let executable = await process.mainModule()
    /// let versions = executable.versionInfo() else return
    /// print(`file {versions.file}, product {versions.product}`)
    /// ```
    @mustUse("use the returned version information")
    fn versionInfo() -> ModuleVersionInfo! {
        let optionalHeader = self.peOptionalHeader()?
        let optionalMagic = process.read<u16>(optionalHeader)?
        if optionalMagic != 0x010b && optionalMagic != 0x020b {
            throw "module has an unsupported PE optional header"
        }
        let resourceDirectoryOffset: u64 = if optionalMagic == 0x010b {
            0x70
        } else {
            0x80
        }

        let resourceDirectory = process.read<[u32; 2]>(
            optionalHeader.add(resourceDirectoryOffset)
        )?
        let resourceRva = resourceDirectory[0]
        if resourceRva == 0 || resourceDirectory[1] == 0 {
            throw "module does not have a resource directory"
        }
        let resourceBase = self.address.add(resourceRva as u64)

        let typeHeader = process.read<[u16; 8]>(resourceBase)?
        let typeEntryCount = typeHeader[6] + typeHeader[7]
        let foundTypeDirectory: address? = None
        let typeIndex: u16 = 0
        while typeIndex < typeEntryCount {
            let entry = resourceBase.add(0x10 + (typeIndex as u64) * 8)
            let id = process.read<u32>(entry)?
            let offset = process.read<u32>(entry.add(4))?
            if id == 0x10 && offset & 0x8000_0000 != 0 {
                foundTypeDirectory = resourceBase.add((offset & 0x7fff_ffff) as u64)
                break
            }
            typeIndex += 1
        }
        let typeDirectory = foundTypeDirectory else return Err("module has no version resource")

        let nameHeader = process.read<[u16; 8]>(typeDirectory)?
        let nameEntryCount = nameHeader[6] + nameHeader[7]
        let foundLanguageDirectory: address? = None
        let nameIndex: u16 = 0
        while nameIndex < nameEntryCount {
            let entry = typeDirectory.add(0x10 + (nameIndex as u64) * 8)
            let offset = process.read<u32>(entry.add(4))?
            if offset & 0x8000_0000 != 0 {
                foundLanguageDirectory = resourceBase.add((offset & 0x7fff_ffff) as u64)
                break
            }
            nameIndex += 1
        }
        let languageDirectory = foundLanguageDirectory else return Err(
            "module version resource has no name directory"
        )

        let languageHeader = process.read<[u16; 8]>(languageDirectory)?
        let languageEntryCount = languageHeader[6] + languageHeader[7]
        let foundDataEntry: address? = None
        let languageIndex: u16 = 0
        while languageIndex < languageEntryCount {
            let entry = languageDirectory.add(0x10 + (languageIndex as u64) * 8)
            let offset = process.read<u32>(entry.add(4))?
            if offset & 0x8000_0000 == 0 {
                foundDataEntry = resourceBase.add(offset as u64)
                break
            }
            languageIndex += 1
        }
        let dataEntry = foundDataEntry else return Err(
            "module version resource has no language entry"
        )

        let versionRva = process.read<u32>(dataEntry)?
        let fixedInfo = self.address.add(versionRva as u64).add(0x28)
        if process.read<u32>(fixedInfo)? != 0xfeef_04bd {
            throw "module has invalid fixed file information"
        }
        let parts = process.read<[u16; 8]>(fixedInfo.add(8))?
        return ModuleVersionInfo {
            file: FileVersion.fromParts(
                parts[1],
                parts[0],
                parts[3],
                parts[2]
            ),
            product: FileVersion.fromParts(
                parts[5],
                parts[4],
                parts[7],
                parts[6]
            ),
        }
    }

    /// Reads the file identity from a Windows PE version resource.
    ///
    /// This is the version of the individual executable or library. Use
    /// [`productVersion()`] when a game identifies releases by product version.
    /// Missing resources, malformed images, and failed reads are errors.
    ///
    /// # Example
    ///
    /// Select a known executable file version
    ///
    /// ```splitscript
    /// let executable = await process.mainModule()
    /// let version = executable.fileVersion() else return
    /// if version == v"1.2.3.4" {
    ///     print("recognized file version 1.2.3.4")
    /// }
    /// ```
    @mustUse("use the returned file version")
    fn fileVersion() -> FileVersion! {
        return self.versionInfo()?.file
    }

    /// Reads the product identity from a Windows PE version resource.
    ///
    /// Product versions can remain stable across modules whose individual file
    /// versions differ. Missing resources, malformed images, and failed reads
    /// are errors.
    ///
    /// # Example
    ///
    /// Select a known product version
    ///
    /// ```splitscript
    /// let executable = await process.mainModule()
    /// let version = executable.productVersion() else return
    /// if version == v"2.0.0.0" {
    ///     print("recognized product version 2.0.0.0")
    /// }
    /// ```
    @mustUse("use the returned product version")
    fn productVersion() -> FileVersion! {
        return self.versionInfo()?.product
    }

    /// Resolves a named function exported by a Windows PE module.
    ///
    /// The parser validates the DOS, PE, optional, export-directory, name,
    /// ordinal, and function tables before returning the mapped function
    /// address. Forwarded exports are rejected because they name another
    /// module and function rather than code within this module.
    ///
    /// # Example
    ///
    /// Resolve a Mono runtime entry point
    ///
    /// ```splitscript
    /// let mono = await process.module("mono-2.0-bdwgc.dll")
    /// let assemblyForeach = mono.peExport("mono_assembly_foreach") else return
    /// ```
    @mustUse("use the resolved export address")
    fn peExport(
        /// Exact case-sensitive export name.
        name: String,
    ) -> address! {
        let optionalHeader = self.peOptionalHeader()?
        let optionalMagic = process.read<u16>(optionalHeader)?
        let exportDirectoryOffset: u64 = 0
        if optionalMagic == 0x010b {
            exportDirectoryOffset = 0x60
        } else if optionalMagic == 0x020b {
            exportDirectoryOffset = 0x70
        } else {
            throw "module has an unsupported PE optional header"
        }
        let exportDirectory = process.read<[u32; 2]>(
            optionalHeader.add(exportDirectoryOffset),
        )?
        let exportRva = exportDirectory[0]
        let exportSize = exportDirectory[1]
        if exportRva == 0 || exportSize < 0x28 {
            throw "module does not have an export directory"
        }
        if (exportRva as u64) + (exportSize as u64) > self.size {
            throw "module export directory lies outside the mapped image"
        }

        let exports = self.address.add(exportRva as u64)
        let functionCount = process.read<u32>(exports.add(0x14))?
        let nameCount = process.read<u32>(exports.add(0x18))?
        let functionsRva = process.read<u32>(exports.add(0x1c))?
        let namesRva = process.read<u32>(exports.add(0x20))?
        let ordinalsRva = process.read<u32>(exports.add(0x24))?
        if functionCount == 0 || nameCount == 0 {
            throw "module export directory has no named functions"
        }
        if (functionsRva as u64) + (functionCount as u64) * 4 > self.size
            || (namesRva as u64) + (nameCount as u64) * 4 > self.size
            || (ordinalsRva as u64) + (nameCount as u64) * 2 > self.size {
            throw "module export table lies outside the mapped image"
        }

        let functions = self.address.add(functionsRva as u64)
        let names = self.address.add(namesRva as u64)
        let ordinals = self.address.add(ordinalsRva as u64)
        let index: u32 = 0
        while index < nameCount {
            let nameRva = process.read<u32>(names.add((index as u64) * 4))?
            if nameRva as u64 >= self.size {
                throw "module export name lies outside the mapped image"
            }
            let candidate = process.readUtf8(self.address.add(nameRva as u64), 256)?
            if candidate == name {
                let ordinal = process.read<u16>(ordinals.add((index as u64) * 2))?
                if ordinal as u32 >= functionCount {
                    throw "module export ordinal is outside the function table"
                }
                let functionRva = process.read<u32>(
                    functions.add((ordinal as u64) * 4),
                )?
                if functionRva as u64 >= self.size {
                    throw "module export function lies outside the mapped image"
                }
                if functionRva >= exportRva
                    && (functionRva as u64) < (exportRva as u64) + (exportSize as u64) {
                    throw "forwarded PE exports are not supported"
                }
                return Ok(self.address.add(functionRva as u64))
            }
            index += 1
        }
        throw `module does not export {name}`
    }

    /// Determines the pointer width of a Windows PE module.
    ///
    /// The DOS, PE, and optional-header signatures are validated before the
    /// PE32 or PE32+ pointer width is returned. Unsupported binary formats and
    /// failed reads are returned as errors.
    ///
    /// # Example
    ///
    /// Inspect a module's pointer width
    ///
    /// ```splitscript
    /// let executable = await process.mainModule()
    /// let pointerSize = retry executable.pointerSize()
    /// ```
    fn pointerSize() -> PointerSize! {
        let optionalHeader = self.peOptionalHeader()?
        let optionalMagic = process.read<u16>(optionalHeader)?
        if optionalMagic == 0x010b {
            return Ok(PointerSize.Bit32)
        }
        if optionalMagic == 0x020b {
            return Ok(PointerSize.Bit64)
        }
        throw "module has an unsupported PE optional header"
    }

    /// Scans a module for a signature.
    ///
    /// The module's address and size define the scanned range. Large modules
    /// are scanned cooperatively across ticks so the autosplitter keeps
    /// yielding to the host.
    ///
    /// # Example
    ///
    /// Scan an entire module
    ///
    /// ```splitscript
    /// let gameAssembly = await process.module("GameAssembly.dll")
    /// let marker = await gameAssembly.scan(sig"48 8B ?? 89")
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(ModuleScan)
    fn scan(
        /// The compiled signature pattern.
        signature: Signature,
    ) -> async address;

    /// Scans for a signature whose signed relative 32-bit operand resolves to
    /// a particular address.
    ///
    /// All candidates in one bounded chunk are checked before the operation
    /// yields. This is useful for executable metadata references where a short
    /// instruction prefix may have many unrelated matches.
    ///
    /// # Example
    ///
    /// Find the instruction that references a known string
    ///
    /// ```splitscript
    /// let module = await process.mainModule()
    /// let metadata: address = 0x1000
    /// let instruction = await module.scanRelative32Target(
    ///     sig"48 8D 0D",
    ///     3,
    ///     metadata,
    /// )
    /// ```
    @mustUse("The matching instruction address is otherwise discarded.")
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(ModuleScanRelative32Target)
    fn scanRelative32Target(
        /// The instruction signature.
        signature: Signature,
        /// Byte offset from the match to the relative operand.
        displacementOffset: u64,
        /// Address to which the operand must resolve.
        target: address,
    ) -> async address;

    /// Scans the module for the first of several signatures.
    ///
    /// One signature is checked in one bounded window per update. The result
    /// identifies both the matching address and candidate index.
    ///
    /// # Example
    ///
    /// Select a module-specific layout
    ///
    /// ```splitscript
    /// let module = await process.mainModule()
    /// let layout = await module.scanAny([sig"48 8B ??", sig"A1 ?? ??"])
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(ModuleScanAny)
    fn scanAny(
        /// Candidate patterns in priority order.
        signatures: [Signature],
    ) -> async SignatureMatch;

    /// Reads a 32-bit relative address at an offset from this module.
    ///
    /// The encoded displacement is resolved relative to the instruction that
    /// follows it. Read failures are returned to the caller.
    ///
    /// # Example
    ///
    /// Resolve a module-relative address
    ///
    /// ```splitscript
    /// let gameAssembly = await process.module("GameAssembly.dll")
    /// let target = retry gameAssembly.readRelative32(0x400)
    /// ```
    fn readRelative32(
        /// Byte offset from the module base.
        offset: u64,
    ) -> address! {
        return process.readRelative32(self.address.add(offset))
    }
}

/// Describes the current timer state.
///
/// Timer state is an exhaustive enum returned by [`timer.state`].
///
/// # Example
///
/// Match the complete timer state
///
/// ```splitscript
/// let label = match timer.state() {
///     TimerState.NotRunning => "Not running",
///     TimerState.Running => "Running",
///     TimerState.Paused => "Paused",
///     TimerState.Ended => "Ended",
///     TimerState.Unknown => "Unknown"
/// }
/// ```
@representation(enum, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable, globalVariable)
@capabilities(Equatable)
enum TimerState {
    /// The timer has not started.
    ///
    /// # Example
    ///
    /// Detect a timer waiting to start
    ///
    /// ```splitscript
    /// let waiting = timer.state() == TimerState.NotRunning
    /// ```
    NotRunning,

    /// The timer is running.
    ///
    /// # Example
    ///
    /// Detect an active run
    ///
    /// ```splitscript
    /// let active = timer.state() == TimerState.Running
    /// ```
    Running,

    /// The timer is paused.
    ///
    /// # Example
    ///
    /// Detect a paused timer
    ///
    /// ```splitscript
    /// let paused = timer.state() == TimerState.Paused
    /// ```
    Paused,

    /// The timer has ended.
    ///
    /// # Example
    ///
    /// Detect a completed timer
    ///
    /// ```splitscript
    /// let complete = timer.state() == TimerState.Ended
    /// ```
    Ended,

    /// The host returned an unknown timer state.
    ///
    /// # Example
    ///
    /// Handle an unknown host state
    ///
    /// ```splitscript
    /// let unrecognized = timer.state() == TimerState.Unknown
    /// ```
    Unknown,
}

/// Attachment-scoped Unity engine facilities.
///
/// The [`Unity`] state provider exposes one read-only value named `unity`.
/// Context members are bound once per process attachment before [`onAttach`]
/// runs and remain available in attached lifecycle blocks and state reads.
///
/// # Example
///
/// Read the active scene through the Unity context
///
/// ```splitscript
/// # state Unity ["game.exe"] {}
/// whileAttached {
///     let active = unity.scenes.active() else return
///     print(active.name)
/// }
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable, globalVariable)
struct UnityContext {
    /// Accesses native Unity scene snapshots and hierarchy roots.
    ///
    /// Discovery is performed once per process attachment and only when the
    /// `unity` context is referenced by the script.
    ///
    /// # Example
    ///
    /// Read every loaded scene
    ///
    /// ```splitscript
    /// state Unity ["game.exe"] {
    ///     scenes = unity.scenes.loaded();
    /// }
    /// ```
    scenes: UnityScenes,
}

/// Reads immutable snapshots from Unity's native scene manager.
///
/// The [`unity`](provider@Unity) context discovers this facility once before
/// [`onAttach`] and can then populate ordinary [`state`] fields. Scene reads
/// return errors rather than partial values, so a transient process-memory
/// failure participates in the state's normal transactional update behavior.
///
/// # Example
///
/// Track active and loaded Unity scenes
///
/// ```splitscript
/// # state Unity ["game.exe"] { scene = unity.scenes.active(); }
/// whileAttached {
///     print(current.scene.name)
/// }
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable, globalVariable)
struct UnityScenes {
    /// Address of Unity's native scene-manager state.
    private address: address,

    /// Pointer width used by the attached Unity player.
    private pointerSize: PointerSize,

    // Reads one non-null native pointer using the attached player's width.
    private fn pointer(address: address) -> address! {
        let value: address = match self.pointerSize {
            PointerSize.Bit32 => process.read<u32>(address)? as address,
            PointerSize.Bit64 => process.read<u64>(address)? as address,
        }
        if value == 0 {
            throw "Unity pointer is null"
        }
        return Ok(value)
    }

    // Finds an exact root GameObject without materializing the whole scene
    // hierarchy. The traversal limit prevents a corrupt linked list from
    // monopolizing an update.
    private fn root(sceneAddress: address, name: String) -> UnityGameObject! {
        let rootStorageOffset: u64 = match self.pointerSize {
            PointerSize.Bit32 => 0x88,
            PointerSize.Bit64 => 0xb0,
        }
        let pointerBytes: u64 = match self.pointerSize {
            PointerSize.Bit32 => 4,
            PointerSize.Bit64 => 8,
        }
        let first = self.pointer(sceneAddress.add(rootStorageOffset))?
        let current = first
        let inspected: u32 = 0

        while inspected < 1024 {
            let next = self.pointer(current)?
            let transform = self.pointer(current.add(pointerBytes * 2))?
            let object = UnityGameObject {
                scenes: self,
                transformAddress: transform,
            }
            if object.name()? == name {
                return Ok(object)
            }

            inspected += 1
            if next == first {
                throw "Unity root GameObject was not found"
            }
            current = next
        }
        throw "Unity root GameObject traversal exceeded its safety limit"
    }

    private fn snapshot(sceneAddress: address) -> UnityScene! {
        if sceneAddress == 0 {
            throw "Unity scene address is unavailable"
        }

        let buildIndexOffset: u64 = match self.pointerSize {
            PointerSize.Bit32 => 0x70,
            PointerSize.Bit64 => 0x98,
        }
        let assetPathOffset: u64 = match self.pointerSize {
            PointerSize.Bit32 => 0x0c,
            PointerSize.Bit64 => 0x10,
        }
        let pathAddress: address = match self.pointerSize {
            PointerSize.Bit32 => process.read<u32>(sceneAddress.add(assetPathOffset))? as address,
            PointerSize.Bit64 => process.read<u64>(sceneAddress.add(assetPathOffset))? as address,
        }
        if pathAddress == 0 {
            throw "Unity scene has no asset path"
        }

        let path = process.readUtf8(pathAddress, 128)?
        let nameStart = match path.lastIndexOf("/") {
            Some(separator) => separator + 1,
            None => 0,
        }
        let nameEnd = if path.endsWith(".unity") {
            path.byteLength() - 6
        } else {
            path.byteLength()
        }
        let name = path.slice(nameStart, nameEnd)?

        return Ok(UnityScene {
            scenes: self,
            address: sceneAddress,
            index: process.read<i32>(sceneAddress.add(buildIndexOffset))?,
            path,
            name,
        })
    }

    /// Reads the currently active scene as an immutable snapshot.
    ///
    /// The snapshot owns the scene's address, build index, asset path, and
    /// derived name. A missing scene or failed component read returns an error,
    /// allowing a state field to retain its preceding accepted value.
    ///
    /// # Example
    ///
    /// Poll the active scene
    ///
    /// ```splitscript
    /// # state Unity ["game.exe"] { activeScene = unity.scenes.active(); }
    /// split {
    ///     return old.activeScene.name != current.activeScene.name
    /// }
    /// ```
    @mustUse("The active scene snapshot is otherwise discarded.")
    fn active() -> UnityScene! {
        let activeSceneOffset: u64 = match self.pointerSize {
            PointerSize.Bit32 => 0x28,
            PointerSize.Bit64 => 0x48,
        }
        let sceneAddress: address = match self.pointerSize {
            PointerSize.Bit32 => process.read<u32>(self.address.add(activeSceneOffset))? as address,
            PointerSize.Bit64 => process.read<u64>(self.address.add(activeSceneOffset))? as address,
        }
        return self.snapshot(sceneAddress)
    }

    /// Reads every currently loaded scene as one immutable array.
    ///
    /// Scene order matches Unity's native loaded-scene table. The operation is
    /// all-or-nothing: an invalid table entry or failed scene component read
    /// returns an error instead of exposing a misleading partial collection.
    ///
    /// # Example
    ///
    /// Compare the active scene with Unity's first loaded scene
    ///
    /// ```splitscript
    /// # state Unity ["game.exe"] {
    /// #     activeScene = unity.scenes.active();
    /// #     loadedScenes = unity.scenes.loaded();
    /// # }
    /// isLoading {
    ///     if current.loadedScenes.isEmpty() {
    ///         return None
    ///     }
    ///     let first = current.loadedScenes[0]
    ///     return current.activeScene.name != first.name
    /// }
    /// ```
    @mustUse("The loaded scene snapshots are otherwise discarded.")
    fn loaded() -> [UnityScene]! {
        let sceneCountOffset: u64 = match self.pointerSize {
            PointerSize.Bit32 => 0x10,
            PointerSize.Bit64 => 0x18,
        }
        let sceneCount = process.read<u32>(self.address.add(sceneCountOffset))?
        let tableAddress: address = match self.pointerSize {
            PointerSize.Bit32 => process.read<u32>(self.address.add(sceneCountOffset + 8))? as address,
            PointerSize.Bit64 => process.read<u64>(self.address.add(sceneCountOffset + 16))? as address,
        }
        if sceneCount != 0 && tableAddress == 0 {
            throw "Unity loaded-scene table is unavailable"
        }

        let scenes: [UnityScene] = []
        for index in 0..<sceneCount {
            let entryOffset: u64 = match self.pointerSize {
                PointerSize.Bit32 => (index as u64) * 4,
                PointerSize.Bit64 => (index as u64) * 8,
            }
            let sceneAddress: address = match self.pointerSize {
                PointerSize.Bit32 => process.read<u32>(tableAddress.add(entryOffset))? as address,
                PointerSize.Bit64 => process.read<u64>(tableAddress.add(entryOffset))? as address,
            }
            scenes.push(self.snapshot(sceneAddress)?)
        }
        return Ok(scenes)
    }

    /// Reads Unity's persistent `DontDestroyOnLoad` scene.
    ///
    /// Unity keeps objects that survive ordinary scene transitions in this
    /// special scene. The result is an immutable snapshot with the same
    /// identity and metadata fields as [`active`](method@UnityScenes.active).
    ///
    /// # Example
    ///
    /// Inspect the persistent scene
    ///
    /// ```splitscript
    /// state Unity ["game.exe"] {
    ///     persistentScene = unity.scenes.persistent();
    /// }
    /// ```
    @mustUse("The persistent scene snapshot is otherwise discarded.")
    fn persistent() -> UnityScene! {
        let sceneOffset: u64 = match self.pointerSize {
            PointerSize.Bit32 => 0x40,
            PointerSize.Bit64 => 0x70,
        }
        return self.snapshot(self.address.add(sceneOffset))
    }
}

/// Captures one Unity scene at a particular polling update.
///
/// Every public field is copied from process memory before the value is
/// committed to state. Consequently, [`old`] scene values remain stable after
/// Unity unloads or reuses their original native addresses.
///
/// # Example
///
/// Inspect a scene transition
///
/// ```splitscript
/// # state Unity ["game.exe"] { scene = unity.scenes.active(); }
/// split {
///     return old.scene.index != current.scene.index
/// }
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable, globalVariable)
struct UnityScene {
    /// Scene-manager context retained for live hierarchy lookups.
    private scenes: UnityScenes,

    /// Native address from which this scene snapshot was read.
    ///
    /// The address is retained for advanced native Unity reads. The other
    /// fields remain valid even if this address becomes unreadable later.
    ///
    /// # Example
    ///
    /// Inspect a scene's native identity
    ///
    /// ```splitscript
    /// # state Unity ["game.exe"] { scene = unity.scenes.active(); }
    /// whileAttached {
    ///     debug print(current.scene.address)
    /// }
    /// ```
    address: address,

    /// Unity build index captured for this scene.
    ///
    /// Unity may report `-1` while a scene is still initializing, so the value
    /// intentionally remains signed.
    ///
    /// # Example
    ///
    /// Start on the first configured scene
    ///
    /// ```splitscript
    /// # state Unity ["game.exe"] { scene = unity.scenes.active(); }
    /// start {
    ///     return current.scene.index == 0
    /// }
    /// ```
    index: i32,

    /// Full asset path captured from Unity.
    ///
    /// A typical value resembles `Assets/Scenes/Forest.unity`. Use
    /// [`name`](field@UnityScene.name)
    /// when only the final scene identifier is needed.
    ///
    /// # Example
    ///
    /// Detect a scene stored under the menu directory
    ///
    /// ```splitscript
    /// # state Unity ["game.exe"] { scene = unity.scenes.active(); }
    /// split {
    ///     return current.scene.path.startsWith("Assets/Scenes/Menu/")
    /// }
    /// ```
    path: String,

    /// Final filename component without the `.unity` extension.
    ///
    /// This is derived from [`path`](field@UnityScene.path) when the snapshot is
    /// read, matching the common scene-name representation used by Unity
    /// autosplitters.
    ///
    /// # Example
    ///
    /// Split when the credits scene becomes active
    ///
    /// ```splitscript
    /// # state Unity ["game.exe"] { scene = unity.scenes.active(); }
    /// split {
    ///     return old.scene.name != "Credits" && current.scene.name == "Credits"
    /// }
    /// ```
    name: String,

    /// Finds a GameObject by an exact hierarchy path.
    ///
    /// The first path segment selects a root object in this scene. Every later
    /// segment selects one direct child. Empty segments and missing objects
    /// return an error. Traversal is bounded so malformed native lists cannot
    /// monopolize an update.
    ///
    /// # Example
    ///
    /// Find the player beneath a world root
    ///
    /// ```splitscript
    /// # state Unity ["game.exe"] {}
    /// whileAttached {
    ///     let scene = unity.scenes.active() else return
    ///     let player = scene.find("World/Player") else return
    ///     print(player.name() else "Unknown")
    /// }
    /// ```
    @mustUse("The discovered Unity GameObject is otherwise discarded.")
    fn find(
        /// Exact slash-separated hierarchy path to resolve.
        path: String,
    ) -> UnityGameObject! {
        let parts = path.split("/")?
        if parts.isEmpty() || parts[0].isEmpty() {
            throw "Unity GameObject path is empty"
        }

        let object = self.scenes.root(self.address, parts[0])?
        let index: u32 = 1
        while index < parts.length() {
            if parts[index].isEmpty() {
                throw "Unity GameObject path contains an empty segment"
            }
            object = object.child(parts[index])?
            index += 1
        }
        return Ok(object)
    }
}

/// A live GameObject in an attached Unity scene hierarchy.
///
/// This value retains the native Transform address used to reach the object.
/// It is a live remote handle rather than an immutable snapshot: scene changes
/// may invalidate it. `component<T>() -> T.Ref!` finds a component whose
/// runtime class matches the declared managed schema class `T`. The resulting
/// typed live reference supports ordinary managed field reads and
/// `.snapshot()` when stable local state is required. Component traversal is
/// bounded to keep a corrupt native component list from monopolizing an
/// update.
///
/// # Example
///
/// Resolve a child object
///
/// ```splitscript
/// # state Unity ["game.exe"] {}
/// whileAttached {
///     let scene = unity.scenes.active() else return
///     let camera = scene.find("World/Player/Camera") else return
///     print(camera.name() else "Unknown")
/// }
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable, globalVariable)
struct UnityGameObject {
    /// Scene-manager context used for native hierarchy traversal.
    private scenes: UnityScenes,

    /// Native Transform address associated with this GameObject.
    private transformAddress: address,

    /// Reads this GameObject's current name.
    ///
    /// The name is decoded from Unity's native GameObject storage on every
    /// call, so a stale or unreadable live handle returns an error.
    ///
    /// # Example
    ///
    /// Inspect a resolved object's name
    ///
    /// ```splitscript
    /// # state Unity ["game.exe"] {}
    /// whileAttached {
    ///     let scene = unity.scenes.active() else return
    ///     let player = scene.find("Player") else return
    ///     print(player.name() else "Unknown")
    /// }
    /// ```
    @mustUse("The Unity GameObject name is otherwise discarded.")
    fn name() -> String! {
        let gameObjectOffset: u64 = match self.scenes.pointerSize {
            PointerSize.Bit32 => 0x1c,
            PointerSize.Bit64 => 0x30,
        }
        let nameOffset: u64 = match self.scenes.pointerSize {
            PointerSize.Bit32 => 0x3c,
            PointerSize.Bit64 => 0x60,
        }
        let gameObject = self.scenes.pointer(self.transformAddress.add(gameObjectOffset))?
        let nativeString = self.scenes.pointer(gameObject.add(nameOffset))?
        let text = self.scenes.pointer(nativeString)?
        return process.readUtf8(text, 128)
    }

    /// Finds one exact direct child by name.
    ///
    /// Prefer [`find`](method@UnityGameObject.find) when several hierarchy
    /// segments are already known.
    ///
    /// # Example
    ///
    /// Resolve a direct child
    ///
    /// ```splitscript
    /// # state Unity ["game.exe"] {}
    /// whileAttached {
    ///     let scene = unity.scenes.active() else return
    ///     let world = scene.find("World") else return
    ///     let player = world.child("Player") else return
    ///     print(player.name() else "Unknown")
    /// }
    /// ```
    @mustUse("The discovered Unity GameObject is otherwise discarded.")
    fn child(
        /// Exact name of the direct child to find.
        name: String,
    ) -> UnityGameObject! {
        let childrenOffset: u64 = match self.scenes.pointerSize {
            PointerSize.Bit32 => 0x50,
            PointerSize.Bit64 => 0x70,
        }
        let pointerBytes: u64 = match self.scenes.pointerSize {
            PointerSize.Bit32 => 4,
            PointerSize.Bit64 => 8,
        }
        let children = self.scenes.pointer(self.transformAddress.add(childrenOffset))?
        let count: u64 = match self.scenes.pointerSize {
            PointerSize.Bit32 => process.read<u32>(self.transformAddress.add(childrenOffset + 8))? as u64,
            PointerSize.Bit64 => process.read<u64>(self.transformAddress.add(childrenOffset + 16))?,
        }
        if count > 128 {
            throw "Unity child traversal exceeded its safety limit"
        }

        for index in 0..<count {
            let transform = self.scenes.pointer(children.add(index * pointerBytes))?
            let child = UnityGameObject {
                scenes: self.scenes,
                transformAddress: transform,
            }
            if child.name()? == name {
                return Ok(child)
            }
        }
        throw "Unity child GameObject was not found"
    }

    /// Finds a descendant by an exact path relative to this GameObject.
    ///
    /// Each slash-separated segment selects one direct child. This does not
    /// perform an ambiguous recursive name search.
    ///
    /// # Example
    ///
    /// Resolve a nested descendant
    ///
    /// ```splitscript
    /// # state Unity ["game.exe"] {}
    /// whileAttached {
    ///     let scene = unity.scenes.active() else return
    ///     let world = scene.find("World") else return
    ///     let camera = world.find("Player/Camera") else return
    ///     print(camera.name() else "Unknown")
    /// }
    /// ```
    @mustUse("The discovered Unity GameObject is otherwise discarded.")
    fn find(
        /// Exact slash-separated child path to resolve.
        path: String,
    ) -> UnityGameObject! {
        let parts = path.split("/")?
        if parts.isEmpty() {
            throw "Unity GameObject path is empty"
        }

        let object = self
        for part in parts {
            if part.isEmpty() {
                throw "Unity GameObject path contains an empty segment"
            }
            object = object.child(part)?
        }
        return Ok(object)
    }

    // Returns the live managed object whose runtime header matches a declared
    // schema class. The public component<T>() operation supplies the cached
    // backend-neutral header resolved during provider preparation.
    private fn componentAddress(expectedHeader: address) -> address! {
        let gameObjectOffset: u64 = match self.scenes.pointerSize {
            PointerSize.Bit32 => 0x1c,
            PointerSize.Bit64 => 0x30,
        }
        let componentObjectOffset: u64 = match self.scenes.pointerSize {
            PointerSize.Bit32 => 0x18,
            PointerSize.Bit64 => 0x28,
        }
        let pointerBytes: u64 = match self.scenes.pointerSize {
            PointerSize.Bit32 => 4,
            PointerSize.Bit64 => 8,
        }
        let gameObject = self.scenes.pointer(self.transformAddress.add(gameObjectOffset))?
        let components = self.scenes.pointer(gameObject.add(gameObjectOffset))?
        let count: u64 = match self.scenes.pointerSize {
            PointerSize.Bit32 => process.read<u32>(gameObject.add(gameObjectOffset + 8))? as u64,
            PointerSize.Bit64 => process.read<u64>(gameObject.add(gameObjectOffset + 16))?,
        }
        if count > 128 {
            throw "Unity component traversal exceeded its safety limit"
        }

        for index in 1..<count {
            let slot = components.add(index * pointerBytes * 2 + pointerBytes)
            let nativeComponent = match self.scenes.pointer(slot) {
                Ok(value) => value,
                Err(_) => continue,
            }
            let managedObject = match self.scenes.pointer(nativeComponent.add(componentObjectOffset)) {
                Ok(value) => value,
                Err(_) => continue,
            }
            let header = match self.scenes.pointer(managedObject) {
                Ok(value) => value,
                Err(_) => continue,
            }
            if header == expectedHeader {
                return Ok(managedObject)
            }
        }
        throw "Unity managed component was not found"
    }
}

/// Describes an attached Unity IL2CPP runtime.
///
/// The runtime stores resolved metadata roots, its version, and pointer size.
///
/// # Example
///
/// Discover a typed Unity runtime
///
/// ```splitscript
/// let unityRuntime = await Unity.il2cpp(2020)
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable)
private struct UnityModule {
    /// Returns the IL2CPP assemblies metadata address.
    ///
    /// # Example
    ///
    /// Inspect the assemblies metadata root
    ///
    /// ```splitscript
    /// let runtime = await Unity.il2cpp(2020)
    /// let assembliesAddress = runtime.assemblies
    /// ```
    assemblies: address,

    /// Returns the IL2CPP type-information table address.
    ///
    /// # Example
    ///
    /// Inspect the type-information table
    ///
    /// ```splitscript
    /// let runtime = await Unity.il2cpp(2020)
    /// let typeInformation = runtime.typeInfoTable
    /// ```
    typeInfoTable: address,

    /// Returns the detected Unity metadata version.
    ///
    /// # Example
    ///
    /// Read the selected Unity layout version
    ///
    /// ```splitscript
    /// let runtime = await Unity.il2cpp(2020)
    /// let metadataVersion = runtime.version
    /// ```
    version: u32,

    /// Returns the attached process pointer size.
    ///
    /// # Example
    ///
    /// Read the Unity process pointer size
    ///
    /// ```splitscript
    /// let runtime = await Unity.il2cpp(2020)
    /// let unityPointerBytes = runtime.pointerSize
    /// ```
    pointerSize: u32,

    /// Finds an IL2CPP image.
    ///
    /// Suspends until the named image is discoverable.
    ///
    /// # Example
    ///
    /// Find a managed assembly
    ///
    /// ```splitscript
    /// let unity = await Unity.il2cpp(2020)
    /// let image = await unity.image("Assembly-CSharp")
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(UnityModuleImage)
    fn image(
        /// The managed assembly name.
        name: String,
    ) -> async UnityImage;
}

/// Describes a Unity assembly image.
///
/// An image retains its owning Unity runtime for subsequent class lookup.
///
/// # Example
///
/// Discover a typed Unity image
///
/// ```splitscript
/// let runtime = await Unity.il2cpp(2020)
/// let assemblyImage = await runtime.image("Assembly-CSharp")
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable)
private struct UnityImage {
    /// Returns the Unity image address.
    ///
    /// # Example
    ///
    /// Inspect a Unity image address
    ///
    /// ```splitscript
    /// let runtime = await Unity.il2cpp(2020)
    /// let image = await runtime.image("Assembly-CSharp")
    /// let imageAddress = image.address
    /// ```
    address: address,

    /// Retains the owning Unity runtime.
    private module: UnityModule,

    /// Finds a class in an IL2CPP image.
    ///
    /// Suspends until the named class is discoverable.
    ///
    /// # Example
    ///
    /// Find a managed class
    ///
    /// ```splitscript
    /// let unity = await Unity.il2cpp(2020)
    /// let image = await unity.image("Assembly-CSharp")
    /// let gameManager = await image.class("GameManager")
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(UnityImageClass)
    fn class(
        /// The managed class name.
        name: String,
    ) -> async UnityClass;

    // Completes one readable metadata probe for all schema aliases. A class
    // with address zero is the compiler-private ambiguity sentinel.
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(UnityImageClassAny)
    private fn probeClassAny(names: [String]) -> async UnityClass?;

    // Resolves exactly one runtime class for a source schema declaration.
    private fn classAny(names: [String]) -> async UnityClass {
        let candidate = await self.probeClassAny(names)
        let class = candidate else {
            print(`no Unity class matches metadata names {names}`)
            await process.closed()
        }
        if class.address == 0 {
            print(`multiple Unity classes match metadata names {names}`)
            await process.closed()
        }
        return class
    }
}

/// Describes a Unity runtime class.
///
/// A class retains its owning Unity runtime for field and static-data discovery.
///
/// # Example
///
/// Discover a typed Unity class
///
/// ```splitscript
/// let runtime = await Unity.il2cpp(2020)
/// let image = await runtime.image("Assembly-CSharp")
/// let playerClass = await image.class("Player")
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable)
private struct UnityClass {
    /// Returns the Unity class address.
    ///
    /// # Example
    ///
    /// Inspect a Unity class address
    ///
    /// ```splitscript
    /// let runtime = await Unity.il2cpp(2020)
    /// let image = await runtime.image("Assembly-CSharp")
    /// let player = await image.class("Player")
    /// let classAddress = player.address
    /// ```
    address: address,

    /// Retains the owning Unity runtime.
    private module: UnityModule,

    // IL2CPP object headers point directly at their Il2CppClass metadata.
    private fn instanceHeader() -> address {
        return self.address
    }

    /// Finds a managed field offset.
    ///
    /// Searches the class hierarchy and recognizes backing fields.
    ///
    /// # Example
    ///
    /// Find a field offset
    ///
    /// ```splitscript
    /// let unity = await Unity.il2cpp(2020)
    /// let image = await unity.image("Assembly-CSharp")
    /// let gameManager = await image.class("GameManager")
    /// let healthOffset = await gameManager.field("health")
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(UnityClassField)
    fn field(
        /// The managed field name.
        name: String,
    ) -> async u32;

    /// Finds the unique field matching one of the supplied metadata names.
    ///
    /// Returns both the field offset and selected candidate index.
    ///
    /// # Example
    ///
    /// Try multiple field names
    ///
    /// ```splitscript
    /// let unity = await Unity.il2cpp(2020)
    /// let image = await unity.image("Assembly-CSharp")
    /// let gameManager = await image.class("GameManager")
    /// let levelField = await gameManager.fieldAny(["currentLevel", "level"])
    /// ```
    fn fieldAny(
        /// Alternative field metadata names.
        names: [String],
    ) -> async UnityField {
        let candidate = await self.probeFieldAny(names)
        let field = candidate else {
            print(`no Unity field matches metadata names {names}`)
            await process.closed()
        }
        return field
    }

    // Completes after one successful metadata traversal. Index !0 is the
    // compiler-private ambiguity sentinel returned by the raw backend probe.
    private fn probeFieldAny(names: [String]) -> async UnityField? {
        let candidate = await self.rawProbeFieldAny(names)
        match candidate {
            Some(field) if field.index == !0 => {
                print(`multiple Unity fields match metadata names {names}`)
                await process.closed()
            },
            _ => return candidate,
        }
    }

    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(UnityClassProbeFieldAny)
    private fn rawProbeFieldAny(names: [String]) -> async UnityField?;

    // Resolves static storage against the field's declaring runtime class.
    private fn staticFieldAny(names: [String]) -> async address {
        let field = await self.fieldAny(names)
        let owner = UnityClass {
            address: field.owner,
            module: self.module,
        }
        return (await owner.staticTable()).add(field.offset as u64)
    }

    // Preserves completed absence for conditional schema fields.
    private fn probeStaticFieldAny(names: [String]) -> async address? {
        let field = await self.probeFieldAny(names)
        return match field {
            Some(field) => {
                let owner = UnityClass {
                    address: field.owner,
                    module: self.module,
                }
                Some((await owner.staticTable()).add(field.offset as u64))
            },
            None => None,
        }
    }

    /// Finds a class's static-field table.
    ///
    /// Suspends until the static storage pointer is non-null.
    ///
    /// # Example
    ///
    /// Find static storage
    ///
    /// ```splitscript
    /// let unity = await Unity.il2cpp(2020)
    /// let image = await unity.image("Assembly-CSharp")
    /// let gameManager = await image.class("GameManager")
    /// let staticTable = await gameManager.staticTable()
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(UnityClassStaticTable)
    fn staticTable() -> async address;

    /// Finds a static singleton instance.
    ///
    /// Combines field discovery, static-table lookup, and a non-null pointer read.
    ///
    /// # Example
    ///
    /// Find a singleton instance
    ///
    /// ```splitscript
    /// let unity = await Unity.il2cpp(2020)
    /// let image = await unity.image("Assembly-CSharp")
    /// let gameManager = await image.class("GameManager")
    /// let instance = await gameManager.staticInstance(["Instance", "_instance"])
    /// ```
    @requires(attachedProcess)
    @cancellation(processClose)
    @availability(onAttach)
    @intrinsic(UnityClassStaticInstance)
    fn staticInstance(
        /// Candidate singleton field names.
        names: [String],
    ) -> async address;
}

/// Describes a Unity runtime field.
///
/// A field exposes its byte offset and metadata index.
///
/// # Example
///
/// Discover a typed Unity field
///
/// ```splitscript
/// let runtime = await Unity.il2cpp(2020)
/// let image = await runtime.image("Assembly-CSharp")
/// let player = await image.class("Player")
/// let healthField = await player.fieldAny(["health", "_health"])
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable)
private struct UnityField {
    /// Returns the instance-field byte offset.
    ///
    /// # Example
    ///
    /// Read a discovered field offset
    ///
    /// ```splitscript
    /// let runtime = await Unity.il2cpp(2020)
    /// let image = await runtime.image("Assembly-CSharp")
    /// let player = await image.class("Player")
    /// let field = await player.fieldAny(["health", "_health"])
    /// let healthOffset = field.offset
    /// ```
    offset: u32,

    /// Returns the metadata field index.
    ///
    /// # Example
    ///
    /// Read a discovered field index
    ///
    /// ```splitscript
    /// let runtime = await Unity.il2cpp(2020)
    /// let image = await runtime.image("Assembly-CSharp")
    /// let player = await image.class("Player")
    /// let field = await player.fieldAny(["level", "_level"])
    /// let levelFieldIndex = field.index
    /// ```
    index: u32,

    /// Returns the runtime metadata class that declares this field.
    ///
    /// Static storage belongs to this class, which may differ from the class
    /// where schema lookup began.
    ///
    /// # Example
    ///
    /// Retain the declaring class during private schema binding
    ///
    /// ```splitscript
    /// let runtime = await Unity.il2cpp(2020)
    /// let image = await runtime.image("Assembly-CSharp")
    /// let player = await image.class("Player")
    /// let field = await player.fieldAny(["health"])
    /// let declaringClass = field.owner
    /// ```
    owner: address,
}

/// Identifies the supported Unity Mono metadata layouts.
///
/// These versions describe Mono's internal target-memory structures, not the
/// marketing version printed by the Mono runtime.
///
/// # Example
///
/// Select a Mono metadata layout
///
/// ```splitscript
/// let monoVersion = MonoVersion.V2
/// ```
@representation(enum, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable, globalVariable)
@capabilities(Equatable)
enum MonoVersion {
    /// Layout used by Unity releases before the V3 metadata change.
    ///
    /// # Example
    ///
    /// Discover a V2 runtime
    ///
    /// ```splitscript
    /// state Unity.mono(MonoVersion.V2) ["legacy-unity-game.exe"] {}
    /// ```
    V2,

    /// Layout used by Unity 2021.2 and newer releases.
    ///
    /// # Example
    ///
    /// Discover a V3 runtime
    ///
    /// ```splitscript
    /// state Unity.mono(MonoVersion.V3) ["modern-unity-game.exe"] {}
    /// ```
    V3,
}

/// Stores one validated Unity Mono target-memory layout.
///
/// The owning [`MonoModule`] keeps this descriptor private so every metadata
/// operation consumes the same centralized layout facts.
///
/// # Example
///
/// Use the layout through a discovered runtime
///
/// ```splitscript
/// let layoutBackedRuntime: MonoModule = await Unity.mono(MonoVersion.V2)
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, localVariable)
private struct MonoLayout {
    /// Offset of the assembly-name pointer.
    private assemblyName: u64,
    /// Offset of the assembly-image pointer.
    private assemblyImage: u64,
    /// Offset of the image class-cache hash table.
    private imageClassCache: u64,
    /// Offset of the hash-table bucket count.
    private hashSize: u64,
    /// Offset of the hash-table bucket array pointer.
    private hashTable: u64,
    /// Offset of a class's parent pointer.
    private classParent: u64,
    /// Offset of a class's name pointer.
    private className: u64,
    /// Offset of a class's namespace pointer.
    private classNamespace: u64,
    /// Offset of a class's vtable-size value.
    private classVtableSize: u64,
    /// Offset of a class's field array pointer.
    private classFields: u64,
    /// Offset of a class's runtime-information pointer.
    private classRuntimeInfo: u64,
    /// Offset of a class's field count.
    private classFieldCount: u64,
    /// Offset of the next class in one cache bucket.
    private classNextCache: u64,
    /// Offset of a field metadata entry's name pointer.
    private fieldName: u64,
    /// Offset of a field metadata entry's value offset.
    private fieldValue: u64,
    /// Byte stride between field metadata entries.
    private fieldStride: u64,
    /// Offset of the static-data pointer within a Mono vtable.
    private vtable: u64,

    // Selects the centralized PE64 layout retained by MonoModule.
    private static fn forVersion(version: MonoVersion) -> MonoLayout {
        return MonoLayout {
            assemblyName: 0x10,
            assemblyImage: 0x60,
            imageClassCache: match version {
                MonoVersion.V2 => 0x4c0,
                MonoVersion.V3 => 0x4d0,
            },
            hashSize: 0x18,
            hashTable: 0x20,
            classParent: 0x30,
            className: 0x48,
            classNamespace: 0x50,
            classVtableSize: 0x5c,
            classFields: 0x98,
            classRuntimeInfo: 0xd0,
            classFieldCount: 0x100,
            classNextCache: 0x108,
            fieldName: 0x8,
            fieldValue: 0x18,
            fieldStride: 0x20,
            vtable: match version {
                MonoVersion.V2 => 0x40,
                MonoVersion.V3 => 0x48,
            },
        }
    }
}

/// Describes an attached Unity Mono runtime.
///
/// The runtime retains its assembly-list root, pointer width, version, and
/// centralized metadata layout. Discovery and traversal yield between retries.
///
/// # Example
///
/// Discover a Mono runtime
///
/// ```splitscript
/// let discoveredMonoModule = await Unity.mono(MonoVersion.V2)
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable, globalVariable)
private struct MonoModule {
    /// Address of Mono's global assembly-list pointer.
    ///
    /// # Example
    ///
    /// Inspect the discovered list root
    ///
    /// ```splitscript
    /// let mono = await Unity.mono(MonoVersion.V2)
    /// let assemblyList = mono.assemblies
    /// ```
    assemblies: address,

    /// Exact target-memory layout version.
    ///
    /// # Example
    ///
    /// Inspect the selected Mono version
    ///
    /// ```splitscript
    /// let mono = await Unity.mono(MonoVersion.V3)
    /// let version = mono.version
    /// ```
    version: MonoVersion,

    /// Native pointer width of the Mono runtime.
    ///
    /// # Example
    ///
    /// Inspect the target pointer width
    ///
    /// ```splitscript
    /// let mono = await Unity.mono(MonoVersion.V2)
    /// let width = mono.pointerSize
    /// ```
    pointerSize: PointerSize,

    /// Centralized target-memory offsets for this runtime.
    private layout: MonoLayout,

    // Implements the attachment work exposed publicly by Unity.mono().
    private static fn discover(version: MonoVersion) -> async MonoModule {
        let runtime = await process.module("mono-2.0-bdwgc.dll")
        let pointerSize = retry runtime.pointerSize()
        if pointerSize != PointerSize.Bit64 {
            print("Unity Mono currently supports only 64-bit Windows runtimes")
            await process.closed()
        }

        let assemblyForeach = retry runtime.peExport("mono_assembly_foreach")
        let instruction = await process.scan(
            assemblyForeach,
            0x100,
            sig"48 8B 0D",
        )
        let assemblies = retry process.readRelative32(instruction.offset(3))
        return MonoModule {
            assemblies,
            version,
            pointerSize,
            layout: MonoLayout.forVersion(version),
        }
    }

    /// Reads one pointer using the runtime's native width.
    ///
    /// A null pointer and a failed read are ordinary errors.
    ///
    /// # Example
    ///
    /// Read a Mono metadata pointer
    ///
    /// ```splitscript
    /// let pointerRuntime = await Unity.mono(MonoVersion.V2)
    /// let firstAssembly = pointerRuntime.readPointer(pointerRuntime.assemblies) else return
    /// ```
    @mustUse("Reading a Mono pointer has no effect unless its result is used.")
    fn readPointer(
        /// Target address containing the native pointer.
        address: address,
    ) -> address! {
        let pointer = self.readNullablePointer(address)?
        if pointer == 0 {
            throw "Mono metadata pointer is null"
        }
        return Ok(pointer)
    }

    // Reads a pointer without rejecting the null sentinel used by metadata
    // linked lists and inheritance chains.
    private fn readNullablePointer(address: address) -> address! {
        return match self.pointerSize {
            PointerSize.Bit32 => process.read<u32>(address)? as address,
            PointerSize.Bit64 => process.read<u64>(address)? as address,
        }
    }

    /// Returns the runtime's pointer width in bytes.
    ///
    /// Metadata table traversal uses this value to advance between native
    /// pointer entries without duplicating target-width logic.
    ///
    /// # Example
    ///
    /// Compute a pointer-table entry address
    ///
    /// ```splitscript
    /// let widthRuntime = await Unity.mono(MonoVersion.V2)
    /// let table: address = 0
    /// let second = table.add(widthRuntime.pointerBytes())
    /// ```
    @mustUse("The pointer width is returned as a value and does not modify the runtime.")
    fn pointerBytes() -> u64 {
        return match self.pointerSize {
            PointerSize.Bit32 => 4,
            PointerSize.Bit64 => 8,
        }
    }

    /// Finds a loaded managed assembly image.
    ///
    /// The lookup retries after yielding until Mono has registered an assembly
    /// whose metadata name exactly matches the requested value.
    ///
    /// # Example
    ///
    /// Find the game's main managed image
    ///
    /// ```splitscript
    /// let imageRuntime = await Unity.mono(MonoVersion.V2)
    /// let managedImage = await imageRuntime.image("Assembly-CSharp")
    /// ```
    @mustUse("A discovered Mono image is required for subsequent class lookup.")
    fn image(
        /// Managed assembly name without a file extension.
        name: String,
    ) -> async MonoImage {
        while true {
            let link = match self.readPointer(self.assemblies) {
                Ok(address) => address,
                Err(_) => 0 as address,
            }
            while link != 0 {
                let assembly = retry self.readPointer(link)
                let next = retry self.readNullablePointer(link.add(self.pointerBytes()))
                let namePointer = retry self.readPointer(
                    assembly.add(self.layout.assemblyName),
                )
                let candidate = retry process.readUtf8(namePointer, 256)
                if candidate == name {
                    let image = retry self.readPointer(
                        assembly.add(self.layout.assemblyImage),
                    )
                    return MonoImage {
                        address: image,
                        module: self,
                    }
                }
                link = next
            }
            await nextTick()
        }
        return MonoImage {
            address: 0,
            module: self,
        }
    }

    // Owns the raw-address traversal exposed through MonoImage.class().
    private fn classAnyInImage(image: address, names: [String]) -> async MonoClass {
        while true {
            let selectedClass: address = 0
            let ambiguous = false
            let cache = image.add(self.layout.imageClassCache)
            let bucketCount = retry process.read<i32>(cache.add(self.layout.hashSize))
            if bucketCount > 0 {
                let table = retry self.readPointer(cache.add(self.layout.hashTable))
                let bucket: i32 = 0
                while bucket < bucketCount {
                    let classAddress = retry self.readNullablePointer(
                        table.add((bucket as u64) * self.pointerBytes()),
                    )
                    while classAddress != 0 {
                        let namePointer = retry self.readPointer(
                            classAddress.add(self.layout.className),
                        )
                        let candidateName = retry process.readUtf8(namePointer, 256)
                        let candidateIndex: u32 = 0
                        while candidateIndex < names.length() {
                            let name = names[candidateIndex]
                            let separator = name.lastIndexOf(".")
                            let expectedName = match separator {
                                Some(index) => name.slice(index + 1, name.byteLength()) else name,
                                None => name,
                            }
                            if candidateName == expectedName {
                                let namespacePointer = retry self.readPointer(
                                    classAddress.add(self.layout.classNamespace),
                                )
                                let candidateNamespace = retry process.readUtf8(
                                    namespacePointer,
                                    256,
                                )
                                let namespaceMatches = match separator {
                                    Some(index) => {
                                        let expectedNamespace = name.slice(0, index) else continue
                                        candidateNamespace == expectedNamespace
                                    },
                                    None => true,
                                }
                                if namespaceMatches {
                                    if selectedClass != 0 && selectedClass != classAddress {
                                        ambiguous = true
                                    }
                                    selectedClass = classAddress
                                }
                            }
                            candidateIndex += 1
                        }
                        classAddress = retry self.readNullablePointer(
                            classAddress.add(self.layout.classNextCache),
                        )
                    }
                    bucket += 1
                }
                if ambiguous {
                    print(`multiple Unity classes match metadata names {names}`)
                    await process.closed()
                } else if selectedClass != 0 {
                    return MonoClass {
                        address: selectedClass,
                        module: self,
                    }
                } else {
                    print(`no Unity class matches metadata names {names}`)
                    await process.closed()
                }
            }
            await nextTick()
        }
        return MonoClass {
            address: 0,
            module: self,
        }
    }

    // Completes after one fully readable traversal, preserving absence.
    private fn probeFieldAnyInClass(
        classAddress: address,
        names: [String],
    ) -> async UnityField? {
        let current = classAddress
        let selectedOffset: u32? = None
        let selectedIndex: u32 = 0
        let selectedOwner: address = 0
        let ambiguous = false
        while current != 0 {
            let count = retry process.read<i32>(
                current.add(self.layout.classFieldCount),
            )
            if count > 0 {
                let fields = retry self.readPointer(
                    current.add(self.layout.classFields),
                )
                let index: i32 = 0
                while index < count {
                    let field = fields.add((index as u64) * self.layout.fieldStride)
                    let namePointer = retry self.readPointer(
                        field.add(self.layout.fieldName),
                    )
                    let candidate = retry process.readUtf8(namePointer, 256)
                    let candidateIndex: u32 = 0
                    let matchingIndex: u32? = None
                    while candidateIndex < names.length() {
                        let name = names[candidateIndex]
                        if candidate == name || candidate == `<{name}>k__BackingField` {
                            matchingIndex = Some(candidateIndex)
                            break
                        }
                        candidateIndex += 1
                    }
                    match matchingIndex {
                        Some(candidateIndex) => {
                            let offset = retry process.read<u32>(
                                field.add(self.layout.fieldValue),
                            )
                            match selectedOffset {
                                Some(previous) if previous != offset || selectedOwner != current => {
                                    ambiguous = true
                                },
                                Some(_) => {},
                                None => {
                                    selectedOffset = Some(offset)
                                    selectedIndex = candidateIndex
                                    selectedOwner = current
                                },
                            }
                        },
                        None => {},
                    }
                    index += 1
                }
            }
            current = retry self.readNullablePointer(current.add(self.layout.classParent))
        }
        if ambiguous {
            print(`multiple Unity fields match metadata names {names}`)
            await process.closed()
        }
        return match selectedOffset {
            Some(offset) => Some(UnityField {
                offset,
                index: selectedIndex,
                owner: selectedOwner,
            }),
            None => None,
        }
    }

    // Resolves exactly one runtime field while traversing one class hierarchy.
    private fn fieldAnyInClass(
        classAddress: address,
        names: [String],
    ) -> async UnityField {
        while true {
            let found = await self.probeFieldAnyInClass(classAddress, names)
            let field = found else {
                print(`no Unity field matches metadata names {names}`)
                await process.closed()
            }
            return field
        }
        return UnityField {
            offset: 0,
            index: 0,
            owner: 0,
        }
    }

    // Owns the raw-address traversal exposed through MonoClass.field().
    private fn fieldInClass(classAddress: address, name: String) -> async u32 {
        let field = await self.fieldAnyInClass(classAddress, [name])
        return field.offset
    }

    // Owns the raw-address traversal exposed through MonoClass.staticTable().
    private fn staticTableForClass(classAddress: address) -> async address {
        while true {
            let runtimeInfo = retry self.readPointer(
                classAddress.add(self.layout.classRuntimeInfo),
            )
            let vtables = retry self.readPointer(runtimeInfo.add(self.pointerBytes()))
            let vtableSize = retry process.read<u32>(
                classAddress.add(self.layout.classVtableSize),
            )
            let tablePointer = vtables
                .add(self.layout.vtable)
                .add((vtableSize as u64) * self.pointerBytes())
            let table = match self.readPointer(tablePointer) {
                Ok(address) => address,
                Err(_) => 0 as address,
            }
            if table != 0 {
                return table
            }
            await nextTick()
        }
        return 0
    }

    // Returns the active MonoVTable pointer stored in object headers.
    private fn instanceHeaderForClass(classAddress: address) -> async address {
        while true {
            let runtimeInfo = retry self.readPointer(
                classAddress.add(self.layout.classRuntimeInfo),
            )
            let vtable = retry self.readPointer(runtimeInfo.add(self.pointerBytes()))
            if vtable != 0 {
                return vtable
            }
            await nextTick()
        }
        return 0
    }
}

/// Describes a managed image loaded by a Unity Mono runtime.
///
/// A Mono image identifies one managed assembly's metadata within its owning
/// runtime. Keeping the runtime with the address lets subsequent class
/// discovery use the correct version-specific metadata layout.
///
/// # Example
///
/// Discover the main game image
///
/// ```splitscript
/// let monoForImage = await Unity.mono(MonoVersion.V2)
/// let mainManagedImage: MonoImage = await monoForImage.image("Assembly-CSharp")
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable, globalVariable)
private struct MonoImage {
    /// Address of the target Mono image metadata.
    ///
    /// # Example
    ///
    /// Inspect an image address
    ///
    /// ```splitscript
    /// let addressRuntime = await Unity.mono(MonoVersion.V2)
    /// let addressImage = await addressRuntime.image("Assembly-CSharp")
    /// let imageAddress = addressImage.address
    /// ```
    address: address,

    /// Runtime that owns this image.
    ///
    /// # Example
    ///
    /// Inspect the image's Mono version
    ///
    /// ```splitscript
    /// let owningRuntime = await Unity.mono(MonoVersion.V3)
    /// let ownedImage = await owningRuntime.image("Assembly-CSharp")
    /// let imageVersion = ownedImage.module.version
    /// ```
    module: MonoModule,

    /// Finds a class by simple or namespace-qualified managed name.
    ///
    /// Namespace-qualified names split at the final dot; simple names match
    /// regardless of the class namespace.
    ///
    /// # Example
    ///
    /// Find a managed game class
    ///
    /// ```splitscript
    /// let namespaceRuntime = await Unity.mono(MonoVersion.V2)
    /// let namespaceImage = await namespaceRuntime.image("Assembly-CSharp")
    /// let namespacedClass = await namespaceImage.class("Example.GameManager")
    /// ```
    @mustUse("A discovered Mono class is required for subsequent field lookup.")
    fn class(
        /// Simple class name or namespace-qualified managed class name.
        name: String,
    ) -> async MonoClass {
        return await self.module.classAnyInImage(self.address, [name])
    }

    // Resolves exactly one class matching the schema's metadata aliases.
    private fn classAny(names: [String]) -> async MonoClass {
        return await self.module.classAnyInImage(self.address, names)
    }
}

/// Describes a class discovered in Unity Mono metadata.
///
/// The value retains both the discovered metadata address and the runtime that
/// knows how to traverse its hierarchy. Field lookup therefore remains tied to
/// the Mono layout used during discovery.
///
/// # Example
///
/// Discover a managed class
///
/// ```splitscript
/// let monoForClass = await Unity.mono(MonoVersion.V2)
/// let imageForClass = await monoForClass.image("Assembly-CSharp")
/// let managedGameClass = await imageForClass.class("GameManager")
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable, globalVariable)
private struct MonoClass {
    /// Address of the target Mono class metadata.
    ///
    /// # Example
    ///
    /// Inspect a class address
    ///
    /// ```splitscript
    /// let classAddressRuntime = await Unity.mono(MonoVersion.V2)
    /// let classAddressImage = await classAddressRuntime.image("Assembly-CSharp")
    /// let addressedClass = await classAddressImage.class("GameManager")
    /// let classAddress = addressedClass.address
    /// ```
    address: address,

    /// Runtime that owns this class.
    ///
    /// # Example
    ///
    /// Inspect the class's pointer width
    ///
    /// ```splitscript
    /// let classWidthRuntime = await Unity.mono(MonoVersion.V2)
    /// let classWidthImage = await classWidthRuntime.image("Assembly-CSharp")
    /// let classWithWidth = await classWidthImage.class("GameManager")
    /// let classPointerSize = classWithWidth.module.pointerSize
    /// ```
    module: MonoModule,

    // Mono object headers point at the class's active MonoVTable.
    private fn instanceHeader() -> async address {
        return await self.module.instanceHeaderForClass(self.address)
    }

    /// Finds a managed field, including C# auto-property backing fields.
    ///
    /// The search walks parent classes and accepts either the requested name or
    /// its compiler-generated C# backing-field spelling.
    ///
    /// # Example
    ///
    /// Find a field offset
    ///
    /// ```splitscript
    /// let offsetRuntime = await Unity.mono(MonoVersion.V2)
    /// let offsetImage = await offsetRuntime.image("Assembly-CSharp")
    /// let offsetClass = await offsetImage.class("GameManager")
    /// let runningOffset = await offsetClass.field("isRunning")
    /// ```
    @mustUse("Field lookup returns an offset and does not modify the class.")
    fn field(
        /// Managed field name or C# auto-property name.
        name: String,
    ) -> async u32 {
        return await self.module.fieldInClass(self.address, name)
    }

    // Resolves exactly one field matching the schema's metadata aliases.
    private fn fieldAny(names: [String]) -> async UnityField {
        return await self.module.fieldAnyInClass(self.address, names)
    }

    // Completes after one successful metadata traversal, preserving absence.
    private fn probeFieldAny(names: [String]) -> async UnityField? {
        return await self.module.probeFieldAnyInClass(self.address, names)
    }

    // Resolves static storage against the field's declaring runtime class.
    private fn staticFieldAny(names: [String]) -> async address {
        let field = await self.fieldAny(names)
        let table = await self.module.staticTableForClass(field.owner)
        return table.add(field.offset as u64)
    }

    // Preserves completed absence for conditional schema fields.
    private fn probeStaticFieldAny(names: [String]) -> async address? {
        let field = await self.probeFieldAny(names)
        return match field {
            Some(field) => {
                let table = await self.module.staticTableForClass(field.owner)
                Some(table.add(field.offset as u64))
            },
            None => None,
        }
    }

    /// Finds the class's static-field storage table.
    ///
    /// The lookup waits until Mono has materialized the class vtable and its
    /// static-data pointer.
    ///
    /// # Example
    ///
    /// Find static storage
    ///
    /// ```splitscript
    /// let storageRuntime = await Unity.mono(MonoVersion.V2)
    /// let storageImage = await storageRuntime.image("Assembly-CSharp")
    /// let storageClass = await storageImage.class("GameManager")
    /// let staticStorage = await storageClass.staticTable()
    /// ```
    @mustUse("Static-table discovery returns an address needed to read static fields.")
    fn staticTable() -> async address {
        return await self.module.staticTableForClass(self.address)
    }

    /// Finds the address of one static field.
    ///
    /// The result combines the class's static storage table with the managed
    /// field offset discovered from metadata.
    ///
    /// # Example
    ///
    /// Find a static field address
    ///
    /// ```splitscript
    /// let staticRuntime = await Unity.mono(MonoVersion.V2)
    /// let staticImage = await staticRuntime.image("Assembly-CSharp")
    /// let staticClass = await staticImage.class("GameManager")
    /// let runningAddress = await staticClass.staticField("isRunning")
    /// ```
    @mustUse("Static-field lookup returns an address and does not modify the class.")
    fn staticField(
        /// Managed static-field name or C# auto-property name.
        name: String,
    ) -> async address {
        return await self.staticFieldAny([name])
    }

    /// Builds a reusable path to one static field.
    ///
    /// Unlike [`staticField`], this keeps the field as a [`MemoryPath`] so further
    /// managed-object pointer dereferences can be appended. Resolving the path
    /// on every poll observes a singleton pointer that changes at runtime.
    ///
    /// # Example
    ///
    /// Follow a static singleton to an instance field
    ///
    /// ```splitscript
    /// let pathRuntime = await Unity.mono(MonoVersion.V2)
    /// let pathImage = await pathRuntime.image("Assembly-CSharp")
    /// let playerStats = await pathImage.class("PlayerStats")
    /// let script = await playerStats.staticFieldPath("script")
    /// let districtOffset = await playerStats.field("currDistrict")
    /// let district = script.dereference(districtOffset as i64)
    /// ```
    @mustUse("A static-field path has no effect unless it is retained or resolved.")
    fn staticFieldPath(
        /// Managed static-field name or C# auto-property name.
        name: String,
    ) -> async MemoryPath {
        let table = await self.staticTable()
        let offset = await self.field(name)
        return table.memoryPath([], offset as i64)
    }
}

/// Retains a discovered GBA emulator memory mapping.
///
/// The runtime-private mapping identifies the emulator backend and translates EWRAM and IWRAM addresses before each read.
///
/// # Example
///
/// Use the attached GBA memory provider
///
/// ```splitscript state GBA
/// let emulator: GBAEmulator = gba
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable)
@capabilities(MemoryReader)
struct GBAEmulator {
    /// Original GBA hardware addresses are 32-bit guest values.
    type Address = u32;

    /// Identifies the emulator-specific memory layout.
    private backend: u32,

    /// Stores the discovered EWRAM base when it is stable.
    private ewram: address,

    /// Stores the discovered IWRAM base when it is stable.
    private iwram: address,

    /// Stores backend-specific discovery state.
    private aux1: address,

    /// Stores backend-specific discovery state.
    private aux2: address,

    /// Stores backend-specific discovery state.
    private aux3: address,

    private static fn resolve64BitMemoryPointer(instruction: address) -> address! {
        let pointer = process.readRelative32(instruction)?
        let opcode = process.read<u8>(instruction.offset(10))?
        if opcode == 0x48 {
            pointer = process.read<address>(pointer)?
        }
        return Ok(pointer)
    }

    // Implements the attachment selected by state GBA.
    private static fn discover() -> async GBAEmulator {
        let processName = process.name()

        if processName == "mGBA.exe" || processName == "mGBA" || processName == "EmuHawk.exe" {
            let mapping = await process.findMemoryRange(
                0x48000,
                MemoryRangeAccess.ReadWrite,
            )
            return GBAEmulator {
                backend: 1,
                ewram: mapping.address,
                iwram: mapping.address.offset(0x40000),
                aux1: 0,
                aux2: 0,
                aux3: 0,
            }
        }

        if processName == "NO$GBA.EXE" {
            let matched = await process.scanMemory(sig"FF 35 ?? ?? ?? ?? 55")
            let basePointer = retry process.read<u32>(matched.offset(2))
            return GBAEmulator {
                backend: 4,
                ewram: 0,
                iwram: 0,
                aux1: basePointer as address,
                aux2: 0,
                aux3: 0,
            }
        }

        if processName == "visualboyadvance-m.exe" || processName == "VisualBoyAdvance.exe" {
            let emulatorModule = await process.mainModule()
            let found = await emulatorModule.scanAny([
                sig"48 8B 05 ?? ?? ?? ?? 81 E3 FF FF 03 00",
                sig"A1 ?? ?? ?? ?? 81 ?? FF FF 03 00",
                sig"81 E6 FF FF 03 00 8B 15 ?? ?? ?? ??",
            ])
            if found.index == 0 {
                let ewramPointer = retry GBAEmulator.resolve64BitMemoryPointer(
                    found.address.offset(3),
                )

                let iwramMatch = await emulatorModule.scan(
                    sig"48 8B 05 ?? ?? ?? ?? 81 E3 FF 7F 00 00",
                )
                let iwramPointer = retry GBAEmulator.resolve64BitMemoryPointer(
                    iwramMatch.offset(3),
                )
                return GBAEmulator {
                    backend: 3,
                    ewram: 0,
                    iwram: 0,
                    aux1: ewramPointer,
                    aux2: iwramPointer,
                    aux3: 0,
                }
            } else if found.index == 1 {
                let ewramPointer = retry process.read<u32>(found.address.offset(1))
                let iwramMatch = await emulatorModule.scan(
                    sig"A1 ?? ?? ?? ?? 81 ?? FF 7F 00 00",
                )
                let iwramPointer = retry process.read<u32>(iwramMatch.offset(1))
                return GBAEmulator {
                    backend: 2,
                    ewram: 0,
                    iwram: 0,
                    aux1: ewramPointer as address,
                    aux2: iwramPointer as address,
                    aux3: 0,
                }
            } else {
                let ewramPointer = retry process.read<u32>(found.address.offset(8))
                return GBAEmulator {
                    backend: 2,
                    ewram: 0,
                    iwram: 0,
                    aux1: ewramPointer as address,
                    aux2: (ewramPointer as address).offset(4),
                    aux3: 0,
                }
            }
        }

        if processName == "retroarch.exe" {
            // A completed absence is meaningful here: it selects the fallback
            // VBA-style core discovery instead of waiting for a direct mapping.
            for mapping in process.memoryRanges() {
                if mapping.address != 0
                    && mapping.size == 0x48000
                    && mapping.readable
                    && mapping.writable
                {
                    return GBAEmulator {
                        backend: 1,
                        ewram: mapping.address,
                        iwram: mapping.address.offset(0x40000),
                        aux1: 0,
                        aux2: 0,
                        aux3: 0,
                    }
                }
            }

            let found = await process.scanMemoryAny([
                sig"48 8B 05 ?? ?? ?? ?? 81 E1 FF FF 03 00",
                sig"A1 ?? ?? ?? ?? 81 ?? FF FF 03 00",
                sig"48 8B 15 ?? ?? ?? ?? 8B 42 40",
                sig"A3 ?? ?? ?? ?? F7 C5 02 00 00 00",
            ])
            if found.index >= 2 {
                let basePointer = if found.index == 2 {
                    retry process.readRelative32(found.address.offset(3))
                } else {
                    retry process.read<u32>(found.address.offset(1)) as address
                }
                let base: address = 0
                if found.index == 2 {
                    base = retry process.read<address>(basePointer)
                } else {
                    base = basePointer
                }
                let ewramMatch = await process.scanMemory(sig"25 FF FF 03 00 88 94 03")
                let ewramOffset = retry process.read<i32>(ewramMatch.offset(8))
                let iwramMatch = await process.scanMemory(sig"25 FE 7F 00 00 66 89 94 03")
                let iwramOffset = retry process.read<i32>(iwramMatch.offset(9))
                return GBAEmulator {
                    backend: 1,
                    ewram: base.offset(ewramOffset as i64),
                    iwram: base.offset(iwramOffset as i64),
                    aux1: 0,
                    aux2: 0,
                    aux3: 0,
                }
            }

            let ewramPointer: address = 0
            if found.index == 0 {
                ewramPointer = retry GBAEmulator.resolve64BitMemoryPointer(
                    found.address.offset(3),
                )
            } else {
                ewramPointer = retry process.read<u32>(found.address.offset(1)) as address
            }
            let iwramMatch = if found.index == 0 {
                await process.scanMemory(
                    sig"48 8B 05 ?? ?? ?? ?? 81 E1 FF 7F 00 00",
                )
            } else {
                await process.scanMemory(sig"A1 ?? ?? ?? ?? 81 ?? FF 7F 00 00")
            }
            let iwramPointer: address = 0
            if found.index == 0 {
                iwramPointer = retry GBAEmulator.resolve64BitMemoryPointer(
                    iwramMatch.offset(3),
                )
            } else {
                iwramPointer = retry process.read<u32>(iwramMatch.offset(1)) as address
            }
            return GBAEmulator {
                backend: if found.index == 0 { 3 } else { 2 },
                ewram: 0,
                iwram: 0,
                aux1: ewramPointer,
                aux2: iwramPointer,
                aux3: 0,
            }
        }

        if processName == "mednafen.exe" {
            let emulatorModule = await process.mainModule()
            let found = await emulatorModule.scanAny([
                sig"48 8B 05 ?? ?? ?? ?? 81 E1 FF FF 03 00",
                sig"A1 ?? ?? ?? ?? 81 ?? FF FF 03 00",
            ])
            let ewramPointer: address = 0
            if found.index == 0 {
                ewramPointer = retry GBAEmulator.resolve64BitMemoryPointer(
                    found.address.offset(3),
                )
            } else {
                ewramPointer = retry process.read<u32>(found.address.offset(1)) as address
            }
            let iwramMatch = if found.index == 0 {
                await emulatorModule.scan(
                    sig"48 8B 05 ?? ?? ?? ?? 81 E1 FF 7F 00 00",
                )
            } else {
                await emulatorModule.scan(sig"A1 ?? ?? ?? ?? 81 ?? FF 7F 00 00")
            }
            let iwramPointer: address = 0
            if found.index == 0 {
                iwramPointer = retry GBAEmulator.resolve64BitMemoryPointer(
                    iwramMatch.offset(3),
                )
            } else {
                iwramPointer = retry process.read<u32>(iwramMatch.offset(1)) as address
            }
            return GBAEmulator {
                backend: if found.index == 0 { 3 } else { 2 },
                ewram: 0,
                iwram: 0,
                aux1: ewramPointer,
                aux2: iwramPointer,
                aux3: 0,
            }
        }

        await process.closed()
        return GBAEmulator {
            backend: 0,
            ewram: 0,
            iwram: 0,
            aux1: 0,
            aux2: 0,
            aux3: 0,
        }
    }

    // A provider mapping is usable only while its complete guest-address
    // translation still reaches readable process memory. The generated
    // provider lifecycle reruns discovery when this probe fails.
    private fn mappingIsAvailable() -> bool {
        let _value = self.read<u8>(0x02000000) else return false
        return true
    }

    /// Reads a typed value from emulated GBA memory.
    ///
    /// The expected MemoryReadable type determines the byte layout. Valid reads lie entirely within EWRAM (0x02000000..0x02040000) or IWRAM (0x03000000..0x03008000).
    ///
    /// # Example
    ///
    /// Read an emulated value
    ///
    /// ```splitscript state GBA
    /// let room: u8 = gba.read(0x03000010) else 0
    /// ```
    @requires(attachedProcess)
    @intrinsic(GBAEmulatorRead)
    fn read<T: MemoryReadable>(
        /// The original GBA hardware address.
        address: u32,
    ) -> T!;
}

/// Retains a discovered PlayStation 2 emulator memory mapping.
///
/// PCSX2 keeps its RAM base behind a native pointer that may change while the
/// emulator is running. RetroArch exposes a stable base for the lifetime of its
/// loaded PS2 core. [`PS2Emulator.read`] hides those backend details and always
/// accepts original PS2 addresses.
///
/// # Example
///
/// Use the attached PS2 memory provider
///
/// ```splitscript state PS2
/// let emulator: PS2Emulator = ps2
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable)
@capabilities(MemoryReader)
struct PS2Emulator {
    /// Original PlayStation 2 addresses are 32-bit guest values.
    type Address = u32;

    /// Identifies how the current emulator exposes its RAM base.
    private backend: u32,

    /// Stores either the RAM base or the native address containing that base.
    private base: address,

    /// Stores backend-specific lifetime state.
    private auxiliary: address,

    // Implements the attachment selected by state PS2.
    private static fn discover() -> async PS2Emulator {
        let processName = process.name()

        if processName == "retroarch.exe" {
            let executable = await process.mainModule()
            let pointerSize = retry executable.pointerSize()
            if pointerSize != PointerSize.Bit64 {
                await process.closed()
            }

            let core = await process.module("pcsx2_libretro.dll")
            let getMemoryData = retry core.peExport("retro_get_memory_data")
            let displacement = await process.scan(
                getMemoryData,
                0x100,
                sig"?? ?? ?? ?? C3",
            )
            let basePointer = retry process.readRelative32(displacement)
            let ramBase = retry process.read<address>(basePointer)
            return PS2Emulator {
                backend: 4,
                base: ramBase,
                auxiliary: core.address,
            }
        }

        let executable = await process.mainModule()
        let pointerSize = retry executable.pointerSize()
        let basePointer = executable.peExport("EEmem") else 0
        if basePointer == 0 {
            if pointerSize == PointerSize.Bit64 {
                let found = await executable.scan(
                    sig"48 8B ?? ?? ?? ?? ?? 25 F0 3F 00 00",
                )
                basePointer = retry process.readRelative32(found.offset(3))
            } else {
                let found = await executable.scanAny([
                    sig"8B ?? ?? ?? ?? ?? 25 F0 3F 00 00",
                    sig"8B ?? ?? ?? ?? ?? 81 ?? F0 3F 00 00",
                ])
                basePointer = retry process.read<u32>(found.address.offset(2)) as address
            }
        }

        return PS2Emulator {
            backend: if pointerSize == PointerSize.Bit64 { 3 } else { 2 },
            base: basePointer,
            auxiliary: 0,
        }
    }

    private fn mappingIsAvailable() -> bool {
        let _value = self.read<u8>(0x00100000) else return false
        return true
    }

    /// Reads a typed value from emulated PlayStation 2 memory.
    ///
    /// The provider's catalogued readable guest-memory range applies to the
    /// complete value. The expected [`MemoryReadable`] type determines its
    /// byte layout.
    ///
    /// # Example
    ///
    /// Read an emulated value
    ///
    /// ```splitscript state PS2
    /// let health: u16 = ps2.read(0x00123456) else 0
    /// ```
    @requires(attachedProcess)
    @intrinsic(Ps2EmulatorRead)
    fn read<T: MemoryReadable>(
        /// The original PlayStation 2 memory address.
        address: u32,
    ) -> T!;
}

/// Retains a discovered PlayStation emulator memory mapping.
///
/// Stable mappings store RAM directly, while DuckStation and PCSX-Redux retain
/// the native pointers needed to refresh a moving RAM base before every read.
/// [`PS1Emulator.read`] always accepts original PlayStation addresses.
///
/// # Example
///
/// Use the attached PlayStation memory provider
///
/// ```splitscript state PS1
/// let emulator: PS1Emulator = ps1
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable)
@capabilities(MemoryReader)
struct PS1Emulator {
    /// Original PlayStation addresses are 32-bit guest values.
    type Address = u32;

    /// Identifies how the selected emulator exposes its RAM base.
    private backend: u32,

    /// Stores either the RAM base or the first native pointer in its path.
    private base: address,

    /// Stores backend-specific lifetime state or a pointer-path offset.
    private auxiliary1: i64,

    /// Stores a second backend-specific pointer-path offset.
    private auxiliary2: i64,

    // Implements the attachment selected by state PS1.
    private static fn discover() -> async PS1Emulator {
        let processName = process.name()
        let executable = await process.mainModule()

        if processName == "ePSXe.exe" {
            let found = await executable.scan(sig"C1 E1 10 8D 89")
            let ramBase = retry process.read<u32>(found.offset(5))
            return PS1Emulator {
                backend: 1,
                base: ramBase as address,
                auxiliary1: 0,
                auxiliary2: 0,
            }
        }

        if processName == "psxfin.exe" {
            let found = await executable.scanAny([
                sig"8B 15 ?? ?? ?? ?? 8D 34 1A",
                sig"A1 ?? ?? ?? ?? 8D 34 18",
                sig"A1 ?? ?? ?? ?? 8B 7C 24 14",
                sig"A1 ?? ?? ?? ?? 8B 6C 24",
            ])
            let pointer = if found.index == 0 {
                retry process.read<u32>(found.address.offset(2))
            } else {
                retry process.read<u32>(found.address.offset(1))
            }
            let ramBase = retry process.read<u32>(pointer as address)
            return PS1Emulator {
                backend: 1,
                base: ramBase as address,
                auxiliary1: 0,
                auxiliary2: 0,
            }
        }

        if processName == "duckstation-qt-x64-ReleaseLTCG.exe"
            || processName == "duckstation-nogui-x64-ReleaseLTCG.exe" {
            if retry executable.pointerSize() != PointerSize.Bit64 {
                await process.closed()
            }
            let basePointer = executable.peExport("RAM") else 0
            if basePointer == 0 {
                let found = await executable.scan(sig"48 89 0D ?? ?? ?? ?? B8")
                basePointer = retry process.readRelative32(found.offset(3))
            }
            return PS1Emulator {
                backend: 3,
                base: basePointer,
                auxiliary1: 0,
                auxiliary2: 0,
            }
        }

        if processName == "retroarch.exe" {
            let pointerSize = retry executable.pointerSize()
            let core = retry {
                process.loadedModule("mednafen_psx_hw_libretro.dll")
                    else process.loadedModule("mednafen_psx_libretro.dll")
                    else process.loadedModule("swanstation_libretro.dll")
                    else process.loadedModule("pcsx_rearmed_libretro.dll")
                    else throw "a supported PlayStation libretro core is not loaded"
            }
            let getMemoryData = retry core.peExport("retro_get_memory_data")
            let ramBase: address = 0

            if core.name == "mednafen_psx_hw_libretro.dll"
                || core.name == "mednafen_psx_libretro.dll" {
                if pointerSize == PointerSize.Bit64 {
                    let found = await process.scan(
                        getMemoryData,
                        0x100,
                        sig"48 0F 44 05",
                    )
                    let target = retry process.readRelative32(found.offset(4))
                    ramBase = retry process.read<address>(target)
                } else {
                    let found = await process.scan(
                        getMemoryData,
                        0x100,
                        sig"0F 44 05",
                    )
                    let pointer = retry process.read<u32>(found.offset(3))
                    ramBase = retry process.read<u32>(pointer as address) as address
                }
            } else if core.name == "swanstation_libretro.dll" {
                if pointerSize == PointerSize.Bit64 {
                    let found = await process.scan(
                        getMemoryData,
                        0x100,
                        sig"48 8B 05 ?? ?? ?? ?? C3",
                    )
                    let target = retry process.readRelative32(found.offset(3))
                    ramBase = retry process.read<address>(target)
                } else {
                    let found = await process.scan(
                        getMemoryData,
                        0x100,
                        sig"74 ?? A1",
                    )
                    let pointer = retry process.read<u32>(found.offset(3))
                    ramBase = retry process.read<u32>(pointer as address) as address
                }
            } else if pointerSize == PointerSize.Bit64 {
                let found = await process.scan(
                    getMemoryData,
                    0x100,
                    sig"48 8B 05 ?? ?? ?? ?? 48 8B 00",
                )
                let target = retry process.readRelative32(found.offset(3))
                let pointer = retry process.read<address>(target)
                ramBase = retry process.read<address>(pointer)
            } else {
                let found = await process.scan(
                    getMemoryData,
                    0x100,
                    sig"0F 44 05 ?? ?? ?? ?? C3",
                )
                let pointer = retry process.read<u32>(found.offset(3))
                ramBase = retry process.read<u32>(pointer as address) as address
            }

            return PS1Emulator {
                backend: 4,
                base: ramBase,
                auxiliary1: core.address as i64,
                auxiliary2: 0,
            }
        }

        if processName == "pcsx-redux.main" {
            if retry executable.pointerSize() != PointerSize.Bit64 {
                await process.closed()
            }
            let found = await executable.scan(
                sig"48 8B 05 ?? ?? ?? ?? 48 8B 80 ?? ?? ?? ?? 48 8B 50 ?? E8",
            )
            let basePointer = retry process.readRelative32(found.offset(3))
            let offset1 = retry process.read<i32>(found.offset(10))
            let offset2 = retry process.read<u8>(found.offset(17))
            return PS1Emulator {
                backend: 5,
                base: basePointer,
                auxiliary1: offset1 as i64,
                auxiliary2: offset2 as i64,
            }
        }

        if processName == "XEBRA.EXE" {
            let found = await executable.scan(
                sig"E8 ?? ?? ?? ?? E9 ?? ?? ?? ?? 89 C8 C1 F8 10",
            )
            let target = retry process.readRelative32(found.offset(1))
            let pointer = retry process.read<u32>(target.offset(0x16a))
            let ramBase = retry process.read<u32>(pointer as address)
            return PS1Emulator {
                backend: 1,
                base: ramBase as address,
                auxiliary1: 0,
                auxiliary2: 0,
            }
        }

        if processName == "mednafen.exe" {
            let found = if retry executable.pointerSize() == PointerSize.Bit64 {
                await executable.scan(sig"89 01 0F B6 82")
            } else {
                await executable.scan(sig"89 01 0F B6 82 ?? ?? ?? ?? C3")
            }
            let ramBase = retry process.read<u32>(found.offset(5))
            return PS1Emulator {
                backend: 1,
                base: ramBase as address,
                auxiliary1: 0,
                auxiliary2: 0,
            }
        }

        await process.closed()
    }

    private fn mappingIsAvailable() -> bool {
        let _value = self.read<u8>(0x80000000) else return false
        return true
    }

    /// Reads a typed value from emulated PlayStation memory.
    ///
    /// Valid reads lie entirely within `0x80000000..=0x817fffff`. The expected
    /// [`MemoryReadable`] type determines the byte layout.
    ///
    /// # Example
    ///
    /// Read an emulated value
    ///
    /// ```splitscript state PS1
    /// let health: u16 = ps1.read(0x80012346) else 0
    /// ```
    @requires(attachedProcess)
    @intrinsic(Ps1EmulatorRead)
    fn read<T: MemoryReadable>(
        /// The original PlayStation memory address.
        address: u32,
    ) -> T!;
}

/// Retains a discovered Sega Master System or Game Gear memory mapping.
///
/// The mapping covers the console's 8 KiB work RAM. Fusion retains the native
/// pointer that can move while the emulator runs; other supported backends keep
/// a stable base and validate libretro core lifetime where applicable.
///
/// # Example
///
/// Use the attached Master System memory provider
///
/// ```splitscript state SMS
/// let emulator: SMSEmulator = sms
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable)
@capabilities(MemoryReader)
struct SMSEmulator {
    /// Original Master System addresses are represented as 32-bit guest values.
    type Address = u32;

    /// Identifies how the selected emulator exposes work RAM.
    private backend: u32,

    /// Stores either the RAM base or a native pointer containing that base.
    private base: address,

    /// Stores a backend-specific offset or lifetime address.
    private auxiliary: i64,

    // Implements the attachment selected by state SMS.
    private static fn discover() -> async SMSEmulator {
        let processName = process.name()
        let executable = await process.mainModule()

        if processName == "Fusion.exe" {
            let found = await executable.scan(sig"74 C8 83 3D")
            let basePointer = retry process.read<u32>(found.offset(4))
            return SMSEmulator {
                backend: 2,
                base: basePointer as address,
                auxiliary: 0xc000,
            }
        }

        if processName == "blastem.exe" {
            let found = await process.scanMemory(
                sig"66 81 E1 FF 1F 0F B7 C9 8A 89 ?? ?? ?? ?? C3",
            )
            let ramBase = retry process.read<u32>(found.offset(10))
            return SMSEmulator {
                backend: 1,
                base: ramBase as address,
                auxiliary: 0,
            }
        }

        if processName == "mednafen.exe" {
            let ramBase = if retry executable.pointerSize() == PointerSize.Bit64 {
                let found = await executable.scan(sig"25 FF 1F 00 00 88 90")
                retry process.read<u32>(found.offset(8))
            } else {
                let found = await executable.scan(sig"25 FF 1F 00 00 0F B6 80")
                retry process.read<u32>(found.offset(7))
            }
            return SMSEmulator {
                backend: 1,
                base: ramBase as address,
                auxiliary: 0,
            }
        }

        if processName == "retroarch.exe" {
            let pointerSize = retry executable.pointerSize()
            let core = retry {
                process.loadedModule("genesis_plus_gx_libretro.dll")
                    else process.loadedModule("genesis_plus_gx_wide_libretro.dll")
                    else process.loadedModule("picodrive_libretro.dll")
                    else process.loadedModule("smsplus_libretro.dll")
                    else process.loadedModule("gearsystem_libretro.dll")
                    else throw "a supported Master System libretro core is not loaded"
            }
            let ramBase: address = 0

            if core.name == "genesis_plus_gx_libretro.dll"
                || core.name == "genesis_plus_gx_wide_libretro.dll" {
                if pointerSize == PointerSize.Bit64 {
                    let found = await core.scan(sig"48 8D 0D ?? ?? ?? ?? 4C 8B 2D")
                    ramBase = retry process.readRelative32(found.offset(3))
                } else {
                    let found = await core.scan(sig"A3 ?? ?? ?? ?? 29 F9")
                    ramBase = retry process.read<u32>(found.offset(1)) as address
                }
            } else if core.name == "picodrive_libretro.dll" {
                if pointerSize == PointerSize.Bit64 {
                    let found = await core.scan(sig"48 8D 0D ?? ?? ?? ?? 41 B8")
                    ramBase = (retry process.readRelative32(found.offset(3))).offset(0x20000)
                } else {
                    let found = await core.scan(sig"B9 ?? ?? ?? ?? C1 EF 10")
                    let base = retry process.read<u32>(found.offset(1))
                    ramBase = (base as address).offset(0x20000)
                }
            } else if core.name == "smsplus_libretro.dll" {
                if pointerSize == PointerSize.Bit64 {
                    let found = await core.scan(sig"31 F6 48 C7 05")
                    ramBase = (retry process.readRelative32(found.offset(5))).offset(4)
                } else {
                    let found = await core.scan(sig"83 FA 02 B8")
                    ramBase = retry process.read<u32>(found.offset(4)) as address
                }
            } else if pointerSize == PointerSize.Bit64 {
                let found = await core.scan(
                    sig"83 ?? 02 75 ?? 48 8B 0D ?? ?? ?? ?? E8",
                )
                let root = retry process.readRelative32(found.offset(8))
                let offsetTarget = retry process.readRelative32(found.offset(21))
                let offset = retry process.read<u8>(offsetTarget.offset(3))
                let first = retry process.read<address>(root)
                let second = retry process.read<address>(first)
                let base = retry process.read<address>(second.offset(offset as i64))
                ramBase = base.offset(0xc000)
            } else {
                let found = await core.scan(
                    sig"83 ?? 02 75 ?? 8B ?? ?? ?? ?? ?? E8",
                )
                let root = found.offset(7)
                let offsetTarget = retry process.readRelative32(found.offset(19))
                let offset = retry process.read<u8>(offsetTarget.offset(2))
                let first = retry process.read<u32>(root)
                let second = retry process.read<u32>(first as address)
                let third = retry process.read<u32>(second as address)
                let base = retry process.read<u32>((third as address).offset(offset as i64))
                ramBase = (base as address).offset(0xc000)
            }

            return SMSEmulator {
                backend: 4,
                base: ramBase,
                auxiliary: core.address as i64,
            }
        }

        await process.closed()
    }

    private fn mappingIsAvailable() -> bool {
        let _value = self.read<u8>(0xc000) else return false
        return true
    }

    /// Reads a typed value from emulated Master System work RAM.
    ///
    /// Valid reads lie entirely within `0xc000..=0xdfff`. The expected
    /// [`MemoryReadable`] type determines the little-endian byte layout.
    ///
    /// # Example
    ///
    /// Read an emulated value
    ///
    /// ```splitscript state SMS
    /// let lives: u8 = sms.read(0xc010) else 0
    /// ```
    @requires(attachedProcess)
    @intrinsic(SmsEmulatorRead)
    fn read<T: MemoryReadable>(
        /// The original Master System work RAM address.
        address: u32,
    ) -> T!;
}

/// Retains a discovered Sega Genesis work-RAM mapping.
///
/// Fusion and Sega Classics retain a native pointer whose target may move.
/// Gens, BlastEm, and the supported libretro cores retain a stable base. The
/// provider also records whether the emulator stores each 16-bit word with its
/// bytes reversed so reads can expose one consistent guest-memory view.
///
/// # Example
///
/// Use the attached Genesis memory provider
///
/// ```splitscript state Genesis
/// let emulator: GenesisEmulator = genesis
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable)
@capabilities(MemoryReader)
struct GenesisEmulator {
    /// Original Genesis work-RAM offsets are represented as 32-bit guest values.
    type Address = u32;

    /// Identifies a stable, moving-pointer, or libretro mapping.
    private backend: u32,

    /// Stores either the RAM base or a native pointer containing that base.
    private base: address,

    /// Stores the libretro core base used for lifetime validation.
    private auxiliary: address,

    /// Indicates that every native 16-bit word needs its bytes reversed.
    private wordSwapped: bool,

    // Implements the attachment selected by state Genesis.
    private static fn discover() -> async GenesisEmulator {
        let processName = process.name()
        let executable = await process.mainModule()

        if processName == "Fusion.exe" {
            let found = await executable.scan(sig"75 2F 6A 01")
            let displacement = retry process.read<u8>(found.offset(1))
            let pointerAddress = found.offset(4 + displacement as i64)
            let basePointer = retry process.read<u32>(pointerAddress)
            return GenesisEmulator {
                backend: 2,
                base: basePointer as address,
                auxiliary: 0,
                wordSwapped: false,
            }
        }

        if processName == "SEGAGameRoom.exe"
            || processName == "SEGAGenesisClassics.exe" {
            let wrapper = process.loadedModule("GenesisEmuWrapper.dll")
            let basePointer = match wrapper {
                Some(module) => {
                    let found = await module.scan(
                        sig"C7 05 ?? ?? ?? ?? ?? ?? ?? ?? A3 ?? ?? ?? ?? A3",
                    )
                    retry process.read<u32>(found.offset(2))
                },
                None => {
                    let found = await executable.scan(sig"89 2D ?? ?? ?? ?? 89 0D")
                    retry process.read<u32>(found.offset(8))
                },
            }
            return GenesisEmulator {
                backend: 2,
                base: basePointer as address,
                auxiliary: 0,
                wordSwapped: true,
            }
        }

        if processName == "gens.exe" {
            let found = await executable.scan(sig"72 ?? 81 ?? FF FF 00 00 66 8B")
            let pointerAddress = found.offset(11)
            let ramBase = retry process.read<u32>(pointerAddress)
            let wordSwapped = retry process.read<u8>(pointerAddress.offset(4)) != 0x86
            return GenesisEmulator {
                backend: 1,
                base: ramBase as address,
                auxiliary: 0,
                wordSwapped,
            }
        }

        if processName == "blastem.exe" {
            let found = await process.scanMemory(
                sig"72 0E 81 E1 FF FF 00 00 66 8B 89 ?? ?? ?? ?? C3",
            )
            let ramBase = retry process.read<u32>(found.offset(11))
            return GenesisEmulator {
                backend: 1,
                base: ramBase as address,
                auxiliary: 0,
                wordSwapped: true,
            }
        }

        if processName == "retroarch.exe" {
            let pointerSize = retry executable.pointerSize()
            let core = retry {
                process.loadedModule("blastem_libretro.dll")
                    else process.loadedModule("genesis_plus_gx_libretro.dll")
                    else process.loadedModule("genesis_plus_gx_wide_libretro.dll")
                    else process.loadedModule("picodrive_libretro.dll")
                    else throw "a supported Genesis libretro core is not loaded"
            }
            let ramBase: address = 0

            if core.name == "blastem_libretro.dll" {
                let found = await process.scanMemory(
                    sig"72 0E 81 E1 FF FF 00 00 66 8B 89 ?? ?? ?? ?? C3",
                )
                ramBase = (retry process.read<u32>(found.offset(11))) as address
            } else if core.name == "genesis_plus_gx_libretro.dll"
                || core.name == "genesis_plus_gx_wide_libretro.dll" {
                if pointerSize == PointerSize.Bit64 {
                    let found = await core.scan(sig"48 8D 0D ?? ?? ?? ?? 4C 8B 2D")
                    ramBase = retry process.readRelative32(found.offset(3))
                } else {
                    let found = await core.scan(sig"A3 ?? ?? ?? ?? 29 F9")
                    ramBase = (retry process.read<u32>(found.offset(1))) as address
                }
            } else if pointerSize == PointerSize.Bit64 {
                let found = await core.scan(sig"48 8D 0D ?? ?? ?? ?? 41 B8")
                ramBase = retry process.readRelative32(found.offset(3))
            } else {
                let found = await core.scan(sig"B9 ?? ?? ?? ?? C1 EF 10")
                ramBase = (retry process.read<u32>(found.offset(1))) as address
            }

            return GenesisEmulator {
                backend: 4,
                base: ramBase,
                auxiliary: core.address,
                wordSwapped: true,
            }
        }

        await process.closed()
    }

    private fn mappingIsAvailable() -> bool {
        let _value = self.read<u8>(0) else return false
        return true
    }

    /// Reads a typed value from emulated Genesis work RAM.
    ///
    /// Valid reads lie entirely within `0x0000..=0xffff`. Unaligned reads work
    /// across 16-bit word boundaries, and primitive values, struct fields, and
    /// fixed-array elements use the Genesis's big-endian byte order.
    ///
    /// # Example
    ///
    /// Read an unaligned emulated value
    ///
    /// ```splitscript state Genesis
    /// let score: u32 = genesis.read(0x1201) else 0
    /// ```
    @requires(attachedProcess)
    @intrinsic(GenesisEmulatorRead)
    fn read<T: MemoryReadable>(
        /// The original Genesis work-RAM offset.
        address: u32,
    ) -> T!;
}

/// Retains a discovered Nintendo GameCube MEM1 mapping.
///
/// Dolphin exposes MEM1 as a stable 24 MiB native mapping. RetroArch uses the
/// same mapping while `dolphin_libretro.dll` remains loaded. Reads accept the
/// original console addresses and decode every [`MemoryReadable`] scalar,
/// struct field, and fixed-array element as big endian.
///
/// # Example
///
/// Use the attached GameCube memory provider
///
/// ```splitscript state GCN
/// let emulator: GCNEmulator = gcn
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable)
@capabilities(MemoryReader)
struct GCNEmulator {
    /// Original GameCube addresses are 32-bit guest values.
    type Address = u32;

    /// Identifies whether the mapping belongs to a standalone or libretro host.
    private backend: u32,

    /// Stores the native start of the console's MEM1 mapping.
    private base: address,

    /// Stores the libretro core base used for lifetime validation.
    private auxiliary: address,

    // Implements the attachment selected by state GCN.
    private static fn discover() -> async GCNEmulator {
        let processName = process.name()
        let coreBase = await dolphinCoreBase()

        let mapping = await process.findMemoryRange(
            0x2000000,
            MemoryRangeAccess.ReadWrite,
        )
        let magic = retry process.read<u32>(mapping.address.offset(0x1c))
        if magic != 0x3d9f33c2 {
            await process.closed()
        }

        return GCNEmulator {
            backend: if processName == "retroarch.exe" { 4 } else { 1 },
            base: mapping.address,
            auxiliary: coreBase,
        }
    }

    private fn mappingIsAvailable() -> bool {
        let _value = self.read<u8>(0x80000000) else return false
        return true
    }

    /// Reads a typed value from emulated GameCube MEM1.
    ///
    /// Valid reads lie entirely within `0x80000000..=0x817fffff`. Primitive
    /// values, struct fields, and fixed-array elements are decoded using the
    /// GameCube's big-endian byte order.
    ///
    /// # Example
    ///
    /// Read an emulated value
    ///
    /// ```splitscript state GCN
    /// let health: u16 = gcn.read(0x80001234) else 0
    /// ```
    @requires(attachedProcess)
    @intrinsic(GCNEmulatorRead)
    fn read<T: MemoryReadable>(
        /// The original GameCube memory address.
        address: u32,
    ) -> T!;
}

/// Retains discovered Nintendo Wii MEM1 and MEM2 mappings.
///
/// Reads accept the original console addresses and decode every
/// [`MemoryReadable`] scalar, struct field, and fixed-array element as big
/// endian. Dolphin and 64-bit RetroArch with `dolphin_libretro.dll` are
/// supported.
///
/// # Example
///
/// Use the attached Wii memory provider
///
/// ```splitscript state Wii
/// let emulator: WiiEmulator = wii
/// ```
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable)
@capabilities(MemoryReader)
struct WiiEmulator {
    /// Original Wii addresses are 32-bit guest values.
    type Address = u32;

    /// Identifies whether the mapping belongs to a standalone or libretro host.
    private backend: u32,

    /// Stores the native start of the console's MEM1 mapping.
    private mem1: address,

    /// Stores the native start of the console's MEM2 mapping.
    private mem2: address,

    /// Stores the libretro core base used for lifetime validation.
    private auxiliary: address,

    // Implements the attachment selected by state Wii.
    private static fn discover() -> async WiiEmulator {
        let processName = process.name()
        let coreBase = await dolphinCoreBase()

        let mem1 = await process.findMemoryRange(
            0x2000000,
            MemoryRangeAccess.ReadWrite,
        )
        let marker1 = retry process.read<u32>(mem1.address.offset(0x3118))
        let marker2 = retry process.read<u32>(mem1.address.offset(0x311c))
        if marker1 != 4 || marker2 != 4 {
            await process.closed()
        }

        let mem2 = await process.findMemoryRange(
            0x4000000,
            MemoryRangeAccess.ReadWrite,
        )
        let mem1Address = mem1.address as u64
        let mem2Address = mem2.address as u64
        if mem2Address <= mem1Address || mem2Address >= mem1Address + 0x10000000 {
            await process.closed()
        }

        return WiiEmulator {
            backend: if processName == "retroarch.exe" { 4 } else { 1 },
            mem1: mem1.address,
            mem2: mem2.address,
            auxiliary: coreBase,
        }
    }

    private fn mappingIsAvailable() -> bool {
        let _value = self.read<u8>(0x80000000) else return false
        return true
    }

    /// Reads a typed value from emulated Wii memory.
    ///
    /// Valid MEM1 addresses lie in `0x80000000..=0x817fffff`; valid MEM2
    /// addresses lie in `0x90000000..=0x93ffffff`. Values and pointer paths use
    /// the Wii's big-endian byte order.
    ///
    /// # Example
    ///
    /// Read an emulated value
    ///
    /// ```splitscript state Wii
    /// let health: u16 = wii.read(0x90001234) else 0
    /// ```
    @requires(attachedProcess)
    @intrinsic(WiiEmulatorRead)
    fn read<T: MemoryReadable>(
        /// The original Wii memory address.
        address: u32,
    ) -> T!;
}

/// Exercises the generic standard-library struct pipeline.
///
/// This declaration exists only in tests and deliberately has no intrinsic implementation.
///
/// # Example
///
/// Read a probe struct
///
/// ```splitscript
/// let probe: CatalogStructProbe = process.read(0x100) else return
/// ```
@testOnly
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable)
@capabilities(Equatable, MemoryReadable)
struct CatalogStructProbe {
    /// Returns the probe value.
    ///
    /// # Example
    ///
    /// Inspect a probe value
    ///
    /// ```splitscript
    /// let probeValue = probe.value
    /// ```
    value: u32,

    /// Builds the constructed-field test fixture.
    ///
    /// Preserves both constructed values through an ordinary source-defined
    /// standard-library body.
    ///
    /// # Example
    ///
    /// Build a constructed-field fixture
    ///
    /// ```splitscript
    /// let values = probe.constructed([3, 5], Some(8))
    /// ```
    fn constructed(
        /// Values stored by the fixture.
        values: [u64; 2],
        /// Optional fallback stored by the fixture.
        fallback: u32?,
    ) -> CatalogConstructedFieldProbe {
        return CatalogConstructedFieldProbe {
            values,
            fallback
        }
    }

    /// Preserves an exact two-element array through generic inference.
    ///
    /// Returns the same pair without widening it to an unsized array.
    ///
    /// # Example
    ///
    /// Keep a pair
    ///
    /// ```splitscript
    /// let pair = probe.fixedPair([3, 5])
    /// ```
    fn fixedPair<T>(
        /// Values stored in the pair.
        values: [T; 2],
    ) -> [T; 2] {
        return values
    }
}

/// Exercises constructed field types in standard-library structs.
///
/// This declaration exists only in tests and verifies that catalog structs use
/// the same array and wrapper type machinery as ordinary source structs.
///
/// # Example
///
/// Store a constructed-field probe
///
/// ```splitscript
/// let fixture: CatalogConstructedFieldProbe = probe
/// ```
@testOnly
@representation(gcStruct, nullable)
@valueUsage(structField, enumPayload, stateField, localVariable)
struct CatalogConstructedFieldProbe {
    /// Returns the stored values.
    ///
    /// # Example
    ///
    /// Inspect fixed values
    ///
    /// ```splitscript
    /// let fixedValues = fixture.values
    /// ```
    values: [u64; 2],

    /// Returns the optional fallback value.
    ///
    /// # Example
    ///
    /// Inspect an optional fallback
    ///
    /// ```splitscript
    /// let optionalFallback = fixture.fallback
    /// ```
    fallback: u32?,
}

/// Exercises fixed-array fields in structural process-memory layouts.
///
/// This declaration exists only in tests and verifies that catalog structs
/// preserve an exact array length while deriving [`MemoryReadable`].
///
/// # Example
///
/// Read a fixed-memory probe
///
/// ```splitscript
/// let memoryProbe: CatalogFixedMemoryProbe = process.read(0x200) else return
/// ```
@testOnly
@representation(gcStruct, nullable)
@valueUsage(localVariable)
@capabilities(MemoryReadable)
struct CatalogFixedMemoryProbe {
    /// Returns three adjacent native-endian values.
    ///
    /// # Example
    ///
    /// Inspect adjacent values
    ///
    /// ```splitscript
    /// let adjacentValues = memoryProbe.values
    /// ```
    values: [u16; 3],
}

/// Exercises derived suspension metadata for catalog-owned source bodies.
///
/// This declaration exists only in tests and verifies direct and transitive
/// suspension without adding an authored [`async`] marker.
///
/// # Example
///
/// Name the suspension fixture
///
/// ```splitscript
/// let fixtureName = "CatalogSuspensionProbe"
/// ```
@testOnly
@representation(gcStruct, nullable)
@valueUsage()
struct CatalogSuspensionProbe {
    /// Keeps the test fixture structurally representable.
    private marker: u8,

    /// Suspends through a trusted leaf operation.
    ///
    /// The body is classified from its resolved call rather than an authored
    /// async annotation.
    ///
    /// # Example
    ///
    /// Await the direct helper
    ///
    /// ```splitscript
    /// await CatalogSuspensionProbe.waitOneTick()
    /// ```
    static fn waitOneTick() -> async None {
        await nextTick()
    }

    /// Suspends transitively through another source-defined helper.
    ///
    /// The callee's derived operation metadata propagates through the ordinary
    /// function call graph.
    ///
    /// # Example
    ///
    /// Await the transitive helper
    ///
    /// ```splitscript
    /// await CatalogSuspensionProbe.waitThroughHelper()
    /// ```
    static fn waitThroughHelper() -> async None {
        await CatalogSuspensionProbe.waitOneTick()
    }
}