SplitScript active roadmap

This file contains only work that is still active, deliberately deferred, or ongoing. Completed milestones belong in docs/ROADMAP_ARCHIVE.md, not as checked boxes here.

The roadmap is ordered by user and porting impact:

Now — the next concrete goal;
P0 — work that blocks faithful autosplitters or protects a foundational compiler boundary;
P1 — important product, tooling, and language expansion after the current porting blockers;
P2 / deferred — useful work that should wait for evidence or a cheaper dependency;
Ongoing — evidence and maintenance expected alongside every priority.

General rules:

Drive language and standard-library growth from reviewed, faithful ports.
Prefer one reusable typed abstraction over compatibility aliases or game-specific compiler branches.
Bring language syntax, semantics, and public standard-library API choices to the user before implementation. Porting evidence should frame the decision and possible designs, not silently choose one.
Keep ordinary library behavior in stdlib/standard.split; reserve Rust for representations, validated intrinsics, runtime helpers, and ABI boundaries.
Add compiler, runtime, formatter, and editor coverage in the same change when a feature crosses those surfaces.
Treat every reported workaround, misunderstanding, and omission as product evidence, including when the intended facility already exists. Classify it as a documentation, compiler-guidance, tooling, language/library, or host-runtime issue instead of dismissing it as port-author error. Lead authors to canonical typed patterns without hiding genuine ergonomic gaps behind migration advice.
Record host-runtime gaps found during ports in docs/RUNTIME_EVOLUTION.md, with evidence and semantic requirements before proposing import spellings. Keep compiler-only work in this roadmap and implemented contracts in docs/ABI.md.
Remove completed work from this file during the next roadmap update and summarize the milestone in the archive.

Now — eliminate confirmed porting-campaign correctness failures

Start with the unchecked tasks in Fix the confirmed 2026-08-30 campaign defects, in their written order. The managed collection schema panic is now stopped at the shared remote-memory validation boundary, and expression-valued optional state fields now apply the same contextual None conversion as other typed positions, and the ASL numeric-root migration now distinguishes main-module offsets from SplitScript absolute addresses. The compiler-owned choice example is corrected and language-catalog validation now parses, formats, and type-checks every complete fixture while classifying focused fragments explicitly. The fixed-array reference now exposes its process-read bounds and the transactional sparse-read alternative. Unknown state providers now list the catalog-owned choices, repair only clear typos, and link a dedicated provider index. Statement-shaped match arms now point at the missing braces and offer a complete rewrite instead of blaming an existing comma. Bare-global lifetime errors now spell out the one direct onAttach/onStart assignment rule and the helper-call boundary. ASL primitive state types now have a physical-width mapping and qualified exact search aliases that do not masquerade as compiler rewrite spellings. Literal provider-memory reads are now checked against the same catalog-owned ranges used by runtime translation and reference documentation. The confirmed campaign-defect sequence is complete, the approved finite process.scanOnce primitive now reports bounded-range exhaustion without changing waiting scans, and suspending whileAttached now supports cancellable post-attachment rediscovery without running timer decisions against stale snapshots. Continue with the remaining P0 porting gaps below. Do not begin managed collection support itself until ASR has a tested representation, and bring every language, standard-library, provider, or host-surface decision below back to the user. Large foreign-input recovery is now bounded and prompt, and the current corpus-proven exact migration searches lead to canonical facilities or honest pending-design pages. Runtime-dependent timer, writable-file, file-metadata, JSON, and module enumeration work remains explicitly deferred until its host contracts are ready. Continue with the highest-impact compiler-only gaps below in the meantime.

Unity schema foundation and deferred follow-ups

Use the Rust Lunistice autosplitter and examples/lunistice.split as the first acceptance pair. The current SplitScript Unity API is not a compatibility boundary: replace its manual image/class/offset plumbing where the schema model provides a clearer typed facility. Keep the generated implementation demand-driven, allocation-conscious, backend-independent, and integrated with the ordinary compiler symbol graph rather than adding Unity-shaped exceptions to inference or code generation.

P0.1 — represent managed metadata in ordinary compiler architecture

P0.2 — bind schemas once per attachment

P0.3 — prove the design by simplifying Lunistice

Declare the Lunistice GameManager and Timer schemas, including shared fields, base-game and DLC-demo conditional shapes, alternative singleton names, LevelTimeParts, and the bounded DLC scene string.
Port examples/lunistice.split from manual class/instance/offset globals and raw process.read calls to generated transactional GameManager and Timer snapshots. The DLC scene is now an ordinary schema-declared String scene maxLength 16 field read as part of the shared snapshot. Preserve all existing autosplitter behavior and keep the user's current local example edits out of intermediate mechanical rewrites.
Add synthetic runtime coverage for both base and DLC metadata shapes, singleton replacement, backing-field lookup, inherited fields, failed reads, and ambiguous shapes. Compare the resulting script structure and behavior with C:\Projekte\lunistice-auto-splitter.
Treat the milestone as complete only when all generated Unity symbols are navigable and documented in the editor and reference viewer, and the port no longer contains manual Unity metadata offsets or attachment bookkeeping.

P1 — complete the Unity object model on the same foundation

Add cooperative T.instances() scanning by managed class/vtable. It returns a completed [T.Ref] snapshot, scans only readable and writable non-executable ranges at natural pointer alignment, bounds bytes and matches per poll, preserves process cancellation, and binds the backend-specific IL2CPP class pointer or Mono vtable once per attachment. Its compiler-provided leaf future, runtime scanner, completion, hover, navigation, highlighting, and Mono/IL2CPP runtime fixtures share the ordinary typed architecture rather than exposing raw vtable machinery.
Unify native scene-manager discovery and immutable active, loaded, and don't-destroy-on-load snapshots under the typed attachment context unity.scenes. State-provider contexts are catalog-declared, resolved through the ordinary symbol graph, prepared once per attachment only when referenced, and available wherever the provider's process value is available. The old public Unity.sceneManager() workflow is private implementation detail.
Add exact, bounded scene hierarchy lookup through UnityScene.find, UnityGameObject.find, and UnityGameObject.child, plus schema-derived UnityGameObject.component<T>() -> T.Ref!. Native traversal lives in privileged SplitScript standard-library source, while the compiler supplies only the declared class's backend-neutral runtime header and nominal result type. A tiny class schema is the typed escape for otherwise-unknown components; defer any raw dynamic API until a real port proves it necessary.
After ASR has a tested implementation, align Unity global managers such as unity.time.frameCount and unity.time.timeScale with it through reachable source-defined declarations rather than independently inventing native discovery or bespoke compiler names. Until then, keep this deferred; the current ASR Unity support covers managed metadata and scenes but not the native time manager.
Add bounded managed-string fields as String field maxLength N and String? field maxLength N. The policy is binding-plan data shared by static, live, and snapshot reads; nullability is typed, overlong payloads fail rather than truncate, UTF-16 replacement decoding is consistent, the raw Process.readManagedString surface is gone, and diagnostics, completion, hover, highlighting, docs, and Lunistice use the schema form.
After ASR has a tested managed-array and managed-list representation, align the schema syntax and runtime model with it rather than independently fixing target layouts in SplitScript. Both should materialize as [T]; do not reintroduce a public List<T> value type. Use Alba and A Short Hike as acceptance ports once that dependency is ready. Separate stable singleton/field chains handled by declarations from collection enumeration that genuinely needs new support. Alba can retain discovered task addresses, names, required values, and previous readings in ordinary growable arrays; it does not need runtime-created state fields. Keep ASR's target families explicit rather than guessing offsets. Dictionaries and A Short Hike's dynamic typed tag values need a separately approved language design based on representative ports.

P0 — make docs-first ASL porting semantically reliable

The first clean-folder exercise had only the compiler and legacy ASL inputs. It produced 52 compiler-valid ports or partial ports across 53 reviewed scripts and learned the language exclusively through splitc docs. Exact Windows executable names and build-specific memory shapes were found, demonstrating that the earlier documentation work helped. Compilation still hid substantial semantic drift: every Unity port combined state Unity with manual runtime and metadata discovery, and emulator ports manually rediscovered mappings and byte order despite matching typed providers.

The 2026-08-30 follow-up independently produced 16 warning-free ports or partial ports and two deliberately unported architecture cases. It confirmed that the schema-first Unity and typed emulator journeys now work when available, while finding a managed-schema compiler panic, inconsistent optional state typing, several diagnostics and compiler-owned examples that mislead authors, and faithful-port gaps around finite scanning, PS2 discovery, persistent files, timer metadata, and runtime-varying memory shapes. Treat silent canonical-API misses and compile-clean semantic substitutions as higher-risk evidence than an explicit compile error. The external exercise directory is disposable evidence, not a durable roadmap dependency; retain actionable conclusions and minimized in-tree regression cases instead of paths or assumptions tied to one generated corpus.

The 2026-09-04 WIP pass produced 33 compiler-clean ports or partial ports, but was less disciplined about behavioral equivalence and repeated one class of literal-precondition observation roughly forty times. Treat its compile-only ports as hypotheses, not validation. Its deep attempts nevertheless add strong independent evidence for runtime-dependent state polling and an associative map, and reinforce the existing timer, writable-file, dynamic-settings, module enumeration, managed-collection, and process-write host gaps. Rechecking the current compiler also confirms that a 166 KiB unmodified legacy ASL still takes more than 60 seconds without producing diagnostics. Conversely, Module.md5, conditional state shapes, finite scans, growable arrays, sets and maps, Instant, and static settings families already cover several reported omissions; those findings are documentation or migration-search work, not reasons to add duplicate APIs.

Turn every reported blocker into an actionable product outcome

Prevent clean-compiling semantic drift

Add a review checklist and compiler-query fixture for ports that compile while bypassing a canonical provider. Check process identity, selected build, provider choice, byte order, lifecycle ownership, settings reachability, integer width, failure behavior, and deliberately omitted source branches. The fixture should assert documentation journeys and diagnostics, not bundle disposable full-script outputs.

Fix the confirmed 2026-08-30 campaign defects

P0 — fix editor correctness and the first-use path

The 2026-08-29 usability and codebase reviews are preserved as evidence in USABILITY.md and CODEBASE_REVIEW.md. The roadmap below keeps their actionable findings, deduplicated against the existing compiler, porting, and packaging work. Exact API facts must continue to come from compiler-owned catalogs; hand-written documents teach tasks and concepts rather than maintaining a parallel inventory.

Give a new author one short successful workflow

Add a compiler-checked, self-contained Getting Started guide with focused inline snippets rather than a bundled or linked full autosplitter. Cover obtaining the extension or CLI, creating a .split file, debug and release builds, neighboring .wasm output, the currently supported host-loading workflow and limitations, opening/searching docs, and reading the first diagnostic. Introduce attachment, one typed setting, one at state field, old / current, and one timer decision before scans, Unity, conditional shapes, or async discovery.
Rewrite the packaged VS Code README as an extension-user/Marketplace artifact: outcome, first workflow, commands and outputs, bundled compiler, documentation, requirements, limitations, and troubleshooting. Move npm, VSIX construction, web-host tests, workers, and Extension Development Host instructions to editors/vscode/DEVELOPMENT.md, linked once for contributors.
Restructure the repository README as an honest audience router. Lead with what an autosplitter author can accomplish, current project/host status, a minimal warning-free example, and paths for extension users, CLI users, ASL porters, and compiler contributors. Route production-port evidence to durable contributor documents and keep backend, LSP, and debug-metadata inventories in developer architecture documents; do not make full examples part of the user path.
Keep maintained port and conformance evidence discoverable for compiler contributors without making the examples directory part of the authoring path. User guides must remain self-contained and must not link to disposable full autosplitter scripts.
Add type-directed completion for enum-backed choice settings. Inside every choice option and its default value, offer enum types in expression position and, after a qualified enum name, only that enum's variants. Reuse ordinary expression/type completion and the setting checker's inferred enum identity rather than maintaining a settings-only symbol list; cover empty, partially written, and already-constrained choice declarations in the shared compiler completion tests used by every editor frontend. The implementation reuses the source-enum candidate builders, narrows later options from the preceding choice entries even while the declaration is incomplete, and excludes payload variants that the choice-setting contract rejects.

Make every documentation surface agree

Correct current contradictions before expanding prose: generic user functions and source async helpers are implemented; strings, structs, arrays, closures, iterators, UTF-16 decoding, numeric formatting, string construction, browsable docs, and generated reference pages must not still be described as future work.
Keep compiler catalogs canonical for exact signatures, effects, availability, members, and support status; hand-written pages should link to those facts instead of copying tables.
Split the user-facing language path from compiler architecture. Route new authors through the self-contained Getting Started workflow, then teach ordinary language, state/memory, settings/timer, failure/async, and advanced providers without depending on full example files. Move HIR, Wasm representation, GC layout, continuation frames, lowering, and DWARF details to COMPILER.md, ABI.md, or a focused developer guide. Give the remaining long concept pages task-named navigation and a table of contents.
Turn the standard-library Markdown into a task-oriented overview linked to generated exact symbol pages. Move its catalog IDs, inference internals, HIR/Wasm IR, compiler context, and backend dispatch material to compiler architecture, and remove manually maintained public-member inventories.
Replace the flat migration capability table and repeated alphabetical catalog renderings with source-first, task-grouped navigation. Within ASL, group attachment/state, process/memory, lifecycle/timer, settings, collections/text, Unity/emulators, and unsupported host behavior. Detailed pages use one consistent shape: source pattern, canonical example, semantic difference, supported hosts, and related reference links; keep catalog IDs in metadata/URLs rather than reader-facing labels. Keep the C#, JavaScript, and Rust guides compact, add a clear next step, and use a few explicit source-spelling to SplitScript-spelling pairs rather than another large table.
Add compact decision guides for lifecycle availability, choosing a state field form, failure/async syntax, and string units. The lifecycle matrix must state timing, available roots/globals, suspension policy, return type, and fallthrough for every action. The other guides should lead from a task to at versus discovery, required versus optional fields, build-specific shapes versus independent discriminators, T? / T! / else / ? / retry / await, and UTF-8 byte, Unicode scalar, UTF-16LE, and managed-string units.
Publish a renderer-produced static HTML reference for web readers so compiler-owned intra-doc links, semantic code highlighting, hierarchy, and search work outside the editor. Generate it in CI rather than committing the roughly half-megabyte reference tree, validate pages, links, anchors, visible examples, and hidden-line removal, and deploy it to GitHub Pages.
Improve generated reference presentation where catalog facts are mechanically correct but user-hostile. Attachment requirements now render as one actionable availability rule instead of overlapping facts; structural type forms use concise source spellings in indexes, headings, breadcrumbs, and member names while retaining capability constraints in their signatures; and onAttach links its core state, shape selection, suspension, and snapshot concepts. Every static example continues through compiler-produced semantic rendering.

P0 — unblock the next representative native ports

Lifecycle semantics exposed by legacy ASL

Add timer-global onStart and onReset actions by sampling timer_get_state near the beginning of each update, before process attachment and state polling. The first update establishes a baseline; later NotRunning -> active and active -> NotRunning transitions fire once, including while detached. Process providers, attachment globals, current, and old remain unavailable. The compiler emits the monitor global, import, and transition code only when either action exists. Script-requested starts and resets are observed naturally on the following update rather than being invoked directly and then rediscovered.
Infer attempt-scoped bare globals from definite onStart assignments, using the same global syntax and viral requirement analysis as attachment state instead of adding a separate attempt block. Generated readiness keeps backend defaults unobservable, detach preserves the values, onReset can inspect them before they are cleared, and a mid-attempt first timer sample deliberately remains only a baseline. Lunistice now uses this state without dummy initializers or reset bookkeeping in whileAttached.
Keep ASL shutdown and exact onSplit delivery as host requirements. Shutdown requires the host to invoke a teardown export before disabling, reloading, or dropping a module; lossless split/skip/undo ordering requires the event contract in R2. Track teardown in R6 of docs/RUNTIME_EVOLUTION.md.

State shapes, discovery, and process identity

Polling, mutable watcher patterns, and settings

Support runtime-dependent state-field activation through ordinary conditional field groups selected by enum-valued state discriminators. The existing state dependency graph polls each discriminator before its selected group, inactive groups perform no reads, and a failed newly active group skips that tick without partially replacing the previous accepted snapshot. A successful shape transition seeds newly visible old / current fields equally. The MCC acceptance regression maps unknown gameIndicator bytes to an explicit source enum fallback, proves that Halo 1 and Halo 2 pointers are mutually exclusive, and proves that an unknown future game ID reads neither group. Attachment-static enum globals cover build-dependent Outer Wilds shapes; Rain World and Bloodstained's pointers that become stale while the process stays open remain part of the separate provider-refresh lifecycle design, not a reason to add a mutable MemoryWatcherList object.
Design and implement one typed associative Map<K, V> now that the MGS signature/checker dispatch, MGS2 room callbacks, Halo objective guards, Bully route tables, and Uncharted Waters route data demonstrate genuine runtime key-to-value lookup. The proposal must compare an equality-backed insertion-order map with a hashed representation before committing to a user-facing Hashable capability, and define stable GC identity, replacement versus insertion, get/absence and indexing semantics, removal, iteration order, mutation-during-iteration behavior, inference, structural Debug/Display, and reachability-driven code generation. Use Map, not a C# Dictionary alias. The approved implementation is an equality-backed, insertion-ordered, stable-identity GC container with new, length, isEmpty, containsKey, insert, indexed read/write (including compound assignment), remove, clear, and entry iteration. Indexing traps for a missing key. There is deliberately no get: callers that care about absence use containsKey, which keeps optional values unambiguous. Iteration yields structurally destructurable MapEntry<K, V> values and supports for { key, value } in map; replacement preserves order while structural mutation invalidates active iteration. Type inference, lazy structural Debug, editor completion, generic standard-library pattern usefulness, runtime behavior, and reachability-driven code generation are covered. Keep focused Dictionary / IDictionary / HashMap migration guidance as a separate follow-up if port evidence shows that generic unknown-name diagnostics are insufficient. Keep heterogeneous ExpandoObject data and runtime settings registration as separate designs.
Add conditional settings visibility or enablement only with explicit host semantics for persisted hidden values and parent changes. Until then, document that headings are visual and parent boolean settings must gate child behavior in source; do not let a compiling hierarchy imply behavior the host does not provide.
Distinguish compile-time settings generation from genuinely runtime-named settings in port reviews. Bounded level and boss tables should use settings families, and statically known entries should use typed settings.name access. Consider runtime registration only for data discovered from the game itself, such as A Short Hike's dynamic tag dictionary, and specify persistence, ordering, duplicate keys, live UI updates, and typed value access before proposing a host API.
Continue [T] as the growable ordered sequence instead of adding a separate List<T> type. Stable wrapper identity, replaceable capacity-backed storage, logical length, amortized push, and capacity-preserving clear now preserve aliases across growth and reset; clearing releases live GC references without reallocating. [T; N] remains fixed-length and does not advertise or accept size-changing methods. Source-defined extend appends a typed array and safely handles self-extension. Source-defined optional pop now composes indexed access with removeAt, returns None without a structural mutation when empty, and retains capacity. Equality-constrained remove(value) now removes the first match and reports absence without a structural mutation. Indexed removeAt shifts in place while preserving aliases and capacity, with explicit bounds behavior. Corpus review found no current indexed-insertion use, so defer that API until maintained-port evidence establishes its semantics. Both array forms retain indexing, iteration, search, length, and values[index] = value replacement. Plain indexed assignment, including compound operators, is non-structural and preserves aliases while evaluating the collection, index, and right operand exactly once. Structural mutation invalidates active iteration without allocating snapshots; preserve that rule for every future collection mutator.

Standard-library and type-system boundaries

Engine and emulator providers

Make physical MemoryReadable layout depend on the concrete reader context. Native address fields use the attached process's detected pointer width and alignment; nested structs, fixed arrays, field offsets, aggregate sizes, and array strides derive recursively from that context. Emulator readers retain their catalog-owned guest width and byte order. Cache layouts by type and context, reserve bounded scratch for the largest supported layout, and show both offsets in hover when a native struct differs between 32-bit and 64-bit targets. Ordinary native pointer paths should infer the process width. Explicit mixed-width reads remain deliberately unimplemented until a real target proves the need and their public spelling is approved.
Decide and implement the source-defined provider mapping lifecycle before claiming parity for emulator cores that unload without their host process exiting. Every emulator provider now owns a private synchronous mapping-validation operation in the catalog. A failed validation ends the logical attachment while retaining the still-open emulator process: attachment-scoped state and continuations are cleared, onDetach runs for a completed attachment, and ordinary cooperative discovery starts again. A replacement mapping runs onAttach and seeds a fresh old / current baseline. Native and Unity providers opt out; the contract is general without adding public syntax.
Finish the schema-first Unity value surface rather than adding another public Mono path API. Bounded managed strings, scalar values, singleton and static roots, and nested references should all be expressible in image / class declarations and consumable by ordinary state snapshots. Use the campaign's mono.Make<T> and mono.MakeString cases to test the schema, its diagnostics, and its documentation; keep staticFieldPath, raw field offsets, object-header arithmetic, and backend-specific target-family traversal private implementation tools. Bring any schema shape that still cannot represent a real port back as a design question before adding public syntax. The final Assemble with Care gap required no new syntax: field binding now retains the declaring runtime class found along the inheritance chain and resolves each static field through that class's storage. A concrete schema can therefore consume a singleton declared by a closed generic base with an ordinary static Concrete instance from "_instance"; declaration. A focused Mono fixture keeps distinct base and derived static tables and rejects the previously plausible wrong-table value.
Verify and extend PS2 guest-memory coverage against ASR before changing the provider boundary. Resident Evil Code: Veronica X reads its disc product code at 0x00015B90, below SplitScript's documented 0x00100000..=0x01ffffff domain, so the canonical provider cannot auto-select a region even though the legacy script can. Determine whether ASR deliberately excludes the low region, whether PCSX2 mappings expose it consistently, and how RetroArch cores differ. Then propose the correct provider domain and runtime validation; do not paper over the gap with a game-specific exception. A 2026-09-02 audit of the current local ASR source confirms that its public PS2 address conversion still documents and enforces 0x00100000..=0x01FFFFFF. Wait for ASR to establish and test the broader domain before changing SplitScript.
Assess an Unreal provider only after representative GWorld, object, and name traversal ports establish the required surface.

P1 — expand migration guidance and automated fixes

Expand the structured foreign-spelling entries beyond the existing declarations, option value, strings, durations, and numeric types. Add new entries only for corpus-proven, unambiguous spellings that are not already handled by the type-aware callable suggestion machinery. Exact HashSet, Dictionary, IDictionary, and HashMap type spellings now recover to the canonical Set and Map names with machine-applicable fixes. Tuple collections lead to named structs, Environment.TickCount and Stopwatch lead to event-anchored Instant use, and duplicate native state searches lead to one state with shape globals and conditional fields. Exact searches for File.GetLastWriteTime, JSON, and Thread.Sleep now identify their pending host/data design or cooperative alternative rather than returning a misleading nearby symbol. Canonical syntax remains unique; no compatibility aliases were added.

P1 — measure and improve interactive compiler queries

Build one request-scoped completion context from the existing recovered SourceDocument, token stream, syntax, cursor, and lazy semantic facts. Remove repeated lex_lossless calls, use the current database before a repair probe, return compact receiver facts rather than cloned programs, and use binary search/partition_point for ordered token and definition-reference cursor lookups with boundary/trivia regressions.
Replace deep per-stage ownership copies with shared immutable compiler products. Share source documents, syntax, and stable resolution inputs through Arc or borrowing; let each later stage own only transformed facts. Measure parse, diagnostics, semantic tokens, hover, and completion on one database before and after, rather than hiding the issue behind additional Clone implementations. Parse, lower, check, and recovery now share one immutable source product; lowered declarations and resolution inputs are shared through strict and recovered checking. The exact-parent 30-sample runner improved every cold generated-source editor query, including diagnostics, both completion shapes, hover, and semantic tokens, while reducing the retained complete-query cache from 13.8 MiB to 9.6 MiB. See docs/BASELINES.md for the stage and query data.
Bound recovery and diagnostic construction on large foreign inputs. The shared recovering lexer now resumes from the failed token boundary instead of re-lexing the complete prefix after every error, with an explicit no-progress fallback for diagnostics whose span excludes the triggering token. Published compiler errors have a deterministic 100-diagnostic budget plus an omitted count while semantic recovery still sees the complete source. Generated regressions cover thousands of independent lexical failures and token-local no-progress recovery without depending on the disposable corpus. The same 165,809-byte legacy ASL that exceeded 60 seconds at revision 57f2564 now returns the bounded, useful diagnostic set in about 0.11 seconds through the max-opt CLI on the same machine.

P1 — source-level debugging after the debugger boundary is chosen

Debug builds should support breakpoints and source stepping in .split files; release builds must remain stripped. Embedded DWARF is the source-level format. Do not add JavaScript source maps. Further implementation is deliberately paused until the JavaScript-debugger experiment is compared with the current native Wasmtime path and a typed-IR interpreter; do not let partially working DWARF displace current porting and language-correctness work.

Prove the Wasmtime/debugger boundary

Before extending native DWARF further, evaluate the JavaScript debugger's WebAssembly support against the real Wasmtime host, especially GC objects. If it still cannot provide a coherent SplitScript-level experience, compare a language-native debugger that interprets typed IR with continuing to adapt native debuggers. Do not commit to a custom DAP until this experiment shows which boundary actually preserves source values and control flow.
Build a minimal fixture against the exact Wasmtime configuration used by LiveSplit. With Config::debug_info(true), verify source breakpoints, stepping, stacks, scalar locals/globals, and GC references across supported debugger/platform combinations. Source stepping works in the Windows host. Wasmtime's native-DWARF transform now preserves source subprogram names and direct scalar local/parameter location lists: direct values use its required trailing DW_OP_stack_value. A Windows CodeLLDB run against the real host now resolves setup, add, and whileAttached, binds source breakpoints, and displays a live scalar local. Emit the supported DW_LANG_C11 compatibility language until SplitScript has an LLDB plugin: DW_LANG_lo_user leaves names and locals hidden. Deliberately omit compilation-unit PC ranges so LLDB derives ownership from complete child subprogram ranges; Wasmtime 45's generic unit range transform drops native regions for non-monotonic control flow. Continue with parameter-liveness cases, globals, GC-backed values, and other debugger / platform combinations. Wasmtime 45 explicitly discards DW_OP_WASM_location for globals and operand-stack values, so compiler tests that merely decode those expressions are insufficient.
Design a debugger-visible representation for source globals. Prefer a debug-only, runtime-independent shadow location in linear memory over hard-coding Wasmtime's private VMContext layout; update the shadow on every source-global write and prove scalar inspection before attempting GC values.
Record Wasm GC inspection as an experimental result. The DWARF-for-Wasm convention locates Wasm values but does not by itself define traversal of structref/arrayref. If standard consumers cannot inspect aggregates, expose honest opaque references first; do not describe Wasmtime's moving GC heap as C-style memory.

Preserve provenance and emit metadata

Carry one single-file source identity through parsing, lowering, checking, and backend planning. CLI builds use the absolute input path, extension builds use VS Code's native file path (or the URI for non-file documents), and intentionally path-less APIs use deterministic input.split. Do not introduce general FileId infrastructure before a real multi-source feature.
Retain source origins for all typed-HIR constructs. Expression and statement/control-flow origins now survive Wasm IR lowering and movement into async poll bodies, and explicit suspend/resume boundaries retain the original await/retry span while generated runtime scaffolding has no source location. Executable enum and aggregate global initializers map _start rows to their declarations; primitive constant expressions correctly have no executable breakpoint address.
Extend the profile-aware DebugArtifactPlan beyond its completed final function-index and function-body maps. Expression instruction boundaries are recorded during encoding, rebased to Code-section-relative DWARF addresses, and verified against wasmparser; async suspend/resume boundaries use distinct line discriminators. Add GC-layout and async-frame-location plans.
Emit a deterministic WebAssembly name section for every imported and defined function in debug builds, including runtime helpers, generic source specializations, async init/poll functions, lifecycle/state readers, and the exported entry points. Release modules contain no name or .debug_* sections.
Extend the same name section beyond the completed source-owned globals, parameters, and direct-function locals. Add GC types, fields, settings storage, and honest names for values moved into async frames after their final index plans expose stable source identities.
Emit deterministic DWARF v5 compilation-unit, source-backed subprogram, and expression line-table sections with gimli::write. Tests decode the result and require every row to land on a real Wasm instruction boundary; release output remains stripped.
Extend the completed primitive scalar types, source-global/direct-function parameter locations, declaration-to-scope local ranges, and statement/control flow rows with enums and honest async-frame variable locations. Suspension and resumption already have distinct rows at the source await/retry span. Add GC aggregates only to the level proven usable by the compatibility fixture.

Integrate the host and editor only after metadata works

Add a debug-profile marker to the SplitScript ABI metadata and enable Wasmtime debug transforms only for debug sessions. Measure startup, tick, and memory overhead.
Prove a manual native-debugger workflow in the real host before adding VS Code UI: attach, state polling, lifecycle actions, retry/await resumption, and module reload.
Prefer a thin VS Code launch/attach integration with a supported native adapter. Build a SplitScript DAP only if the compatibility experiment proves a concrete source-language or GC inspection gap.
Add deterministic artifact tests, backtrace/source-line coverage, and a documented host/Wasmtime/debugger/platform capability matrix.

References:

P1 — harden and publish the portable toolchain

The extension already bundles the same Rust compiler and language service as optimized core Wasm in separate browser-compatible workers. Desktop and web extension hosts support language features, release builds, and revision-safe debug watch without external executables. Native splitc and splitls remain separate first-class products. The architecture experiment is complete; the remaining work is product hardening and distribution.

Hosted browser IDE

Build a deployment-sized Code OSS web proof of concept with the packaged SplitScript extension preinstalled. Record upstream/license obligations, branding, extension-gallery policy, static hosting requirements, payload, startup, memory, and maintenance cost. @vscode/test-web remains test infrastructure, not a redistributable product.
Define persistent browser workspaces and Wasm artifact download/export, then add curated examples, templates, documentation links, and a settings preview without forking the compiler or language service.
Package the workbench and extension with content hashes and a strict CSP; test Chromium, Firefox, and Safari. Keep a custom Monaco shell only as a fallback if Code OSS proves unsuitable.

P1 — remaining language and runtime breadth

P2 — documentation and editor evolution

Render generic type parameters consistently in generated documentation indexes and navigation. All spellings already derive from canonical type- constructor metadata; the inconsistency came from serializing a unary form such as Set<T> as raw Markdown, where <T> was consumed as an HTML tag while Map<K, V> happened to survive. Compiler-generated symbol labels now share one Markdown-boundary escaping function, while catalog identities stay raw. Catalog-wide terminal and HTML tests round-trip every current and future type constructor through root indexes, declaration headings, breadcrumbs, and search results, preventing the same class of drift from recurring.
Make exact documentation queries for concrete generic members resolve to their canonical operation instead of only returning a ranked type list. For example, splitc docs MapEntry.key shows the specialized field. Concise generic owner/member aliases are derived from catalog identities and resolve directly only when they identify one canonical public page; private iterator cursor implementations deliberately have no documentation topics.
Improve navigation for very long terminal guide results without changing their content model. Put stable exact subsection identities near the top of monolithic guides and make focused splitc docs queries obvious before a terminal or calling tool truncates later sections. Treat this as mitigated and lower priority because exact-topic searches already work; do not split the canonical guide into duplicated prose.
Add document highlights for every source-owned occurrence of the symbol under the cursor, with read/write classification, and type-definition navigation for inferred source and catalog types.
Extend document highlights to compiler-owned standard-library and language symbols without resolving every token independently. Add folding ranges for declarations, blocks, multiline expressions, comments, and settings trees once their recovered-syntax boundaries are stable.
Add call hierarchy after the compiler exposes one reusable call graph, multi-range formatting when it materially improves editor workflows, and debugger inline values together with the eventual debugging strategy. Do not prioritize implementation hierarchy, linked editing, document colors, or inline completion without a concrete SplitScript use case.
Add completion snippets for lifecycle blocks, struct construction, and common standard-library calls. Module scope plus state, settings, and tick-rate declarations are grammar-aware already; contextual match-pattern completion is tracked at P1 with the rest of pattern matching. Keep candidates compiler-owned and the VS Code client thin.
Continue adding focused labels, notes, and machine-applicable fixes for real confusing cases rather than growing a speculative diagnostic catalog.
Introduce file identities, modules, and imports only together with a real multi-source use case. Most autosplitters should remain pleasant as one file.

P2 — architecture, verification, and release scaling

Add one catalog-owned constant-precondition analysis rather than a family of one-off lints. When compile-time evaluation proves that a literal call or operation must fail, trap, or never complete, diagnose it using the same constraint metadata that documents the API; do not repeat the porting report's roughly forty separate variants. Cover empty or undersized scan patterns, decoder and collection bounds, invalid rates and radices, empty delimiters, literal parsing, division by zero, provider address domains, empty reduction identities, and literal file paths as those contracts are represented. Decide warning versus error based on whether the failure can be intentionally handled through T!, provide focused fixes, and ignore values that are not statically known. Keep cross-platform executable spelling and host path normalization out of this value analysis.
Decompose broad backend and type-checking coordinators by semantic ownership under existing behavior tests. Extract structural expression, call dispatch, numeric, string/collection, process/memory, and suspension emitters with narrow inputs; separate call candidate collection, generic solving/selection, and diagnostic construction. Move one family at a time and do not replace one all-purpose context with nested bags of everything.
Compile each unique runtime (source, output, profile) artifact once in cargo xtask check, validate it once, and run all argument/scenario variants against that artifact. Compilation is modeled separately from runtime scenarios; fixture planning rejects conflicting output definitions and exact duplicate scenarios without reducing maintained host coverage. The current matrix compiles and validates 65 artifacts for 93 runtime scenarios instead of rebuilding 28 duplicate artifacts.
Add a small shared instantiateRuntimeFixture host for common Wasm loading, text/memory helpers, default imports, _start, and update, while keeping unusual host behavior and assertions local. Migrate harnesses only when touched so focused tests do not acquire an oversized universal host.
Consolidate desktop/browser compiler-worker and language-client lifecycle policy behind host-neutral controllers parameterized by worker creation, transport, message, subscription, and error adapters. Keep Node and browser entry points thin and run the same start, restart, cancellation, failure, and stop contract tests through both adapters.
Extend the VS Code compiler-task harness beyond saved-document identity to exercise release/watch stale-result suppression, atomic output replacement, and temporary-file cleanup through host-neutral controller tests. The production paths already guard these cases; this is regression hardening rather than a known editor correctness defect.
Replace the opaque aggregate documentation fingerprint with reviewable checked-in metadata or per-page fingerprints that report changed URIs and fields. Provide an explicit regeneration command; retain full graph, link, anchor, and example validation as the semantic guard.
Tighten release reproducibility and licensing: pin Rust through rust-toolchain.toml, pin third-party Actions to reviewed commit SHAs, add the declared MIT and Apache-2.0 license texts to source and packages, and inherit shared Rust version/edition/license fields from [workspace.package]. Keep extension versioning independent only if release policy says so.

P2 / deliberately deferred

Ongoing — evidence, correctness, and maintainability

Recommended execution order

Coordinate the read-only timer metadata/time surface, imperative timer control, writable files, read-only file metadata, JSON, and safe module enumeration with their host-runtime contracts. Abe's Oddysee, Outer Wilds, Ato, Spider-Man, and the SEGA Master Splitter are the acceptance evidence; deterministic executable identity already exists through Module.md5().
Resume measured compiler/editor performance, release hardening, hosted IDE, and debugging work after the correctness and product-design sequence above.
Keep only the portions of shared readable-memory helpers that need a new host primitive, the PS2 low-memory domain, unity.time, Sega CD, SNES, and managed collections gated on tested ASR evidence. Keep writes/injection, physical None specialization, and other broad host powers deferred until their explicit dependencies and policies are ready.

FilesExpand file tree

TODO.md

Latest commit

History