WAP LabsProject atlas

docs/waves/wmlscript_spec_traceability.md

Waves WMLScript Spec Traceability

Version: v0.5 Status: Active thematic baseline; all selected SCR and nested clauses authoritative

Purpose

This document captures WMLScript requirements and acceptance criteria (AC) directly from the source specs so Waves can track implementation and test coverage against normative items.

Source Authority Policy

  • See docs/waves/SOURCE_AUTHORITY_POLICY.md for normative vs supplemental source precedence and citation rules.

Source set reviewed (full pass)

  • spec-processing/source-material/WAP-193-WMLScript-20001025-a.pdf
  • spec-processing/source-material/WAP-193_101-WMLScript-20010928-a.pdf
  • spec-processing/source-material/WAP-194-WMLScriptLibraries-20000925-a.pdf
  • spec-processing/source-material/WAP-194_103-WMLScriptLibraries-20020318-a.pdf

Normative precedence for Waves

  1. Use WAP-193_101 as the primary WMLScript core baseline (same core content, updated SCR formatting and split encoder/interpreter IDs).
  2. Use WAP-194 as the standard library baseline.
  3. Apply WAP-194_103 on top of WAP-194 for immediate-refresh conformance clarification (section 11.7 / SCR addition).

Compliance target and prioritization

  • Strict target: implement and prove all 121 mandatory WMLScript and WMLScript Libraries interpreter rows selected by the WAP 1.2.1 Class C profile. A percentage estimate is not a conformance claim.
  • Optional capabilities are declared separately; enhancements may improve internals or UX but may not replace strict observable behavior.
  • Strategy: close bedrock compliance gaps first, then broaden library/function coverage.
  • Bedrock-first requirement groups:
    • RQ-WMLS-001, RQ-WMLS-002, RQ-WMLS-003 (external callable model, pragmas, URL/script invocation ownership)
    • RQ-WMLS-004, RQ-WMLS-005, RQ-WMLS-006 (function semantics, locals/initialization, conversion/type behavior)
    • RQ-WMLS-008, RQ-WMLS-009, RQ-WMLS-010 (bytecode structure verification and trap model)
    • RQ-WMLS-011 (WMLScript content-type routing/handoff)
  • Full closure of optional/profile-gated items (O) remains explicitly staged behind mandatory (M) bedrock behavior.

Current implementation posture

  • Waves has active WaveScript/WMLScript runtime implementation in engine-wasm/engine/src/wavescript/*.
  • Registered units without manual entry-point PCs now route through the strict WAP-193 compilation-unit decoder, whole-unit verification, standard-library reference validation, reachable whole-function stack dataflow, and external function-name table. The executable subset is intentionally limited to RETURN_ES; every other structurally valid opcode returns a deterministic typed unsupported-execution failure.
  • The project-specific nine-opcode VM remains an explicit fixture compatibility boundary selected only by registering manual entry-point PCs. It is not WAP-193 evidence.
  • Exact machine-readable authority:
    • spec-processing/source-manifests/wap-1.2.1-wmlscript-scr.json
    • spec-processing/source-manifests/wap-1.2.1-wmlscript-libraries-scr.json
  • Human audit:
    • docs/waves/WAP_1_2_1_WMLSCRIPT_SCR_LEDGER.md
    • docs/waves/WAP_1_2_1_WMLSCRIPT_LIBRARIES_SCR_LEDGER.md
  • Selected-row audit:
    • WMLScript: 41 required, 32 partial / 9 missing / 0 implemented;
    • Libraries: 80 required, 21 partial / 59 missing / 0 implemented;
    • Direct normative test links: WMLScript 22 and Libraries 7; broader execution evidence stays provisional or mapped-gap.
  • Nested-clause plan:
    • WMLScript: all 41 selected parents / 107 deduplicated clauses;
    • WMLScript Libraries: all 80 selected parents / 211 deduplicated clauses.
  • Work-plan source of truth for closure sequencing:
    • docs/waves/WORK_ITEMS.md (Phase W, Phase W1)
    • docs/waves/SPEC_TEST_COVERAGE.md

The RQ-WMLS-* groups below organize work. They do not replace exact SCR status, and a checked thematic acceptance box must not be read as closing an SCR unless the machine ledger links direct normative evidence.

Requirement matrix

Legend:

  • M = mandatory in spec conformance tables
  • O = optional in spec conformance tables

RQ-WMLS-001: External callable model

  • Requirement:
    • Only extern functions are callable externally.
    • Compilation units used from WML/external calls must resolve function by URL + fragment function name.
  • Spec references:
    • WAP-193_101 6.4.1, 6.4.2.2, 8.3.2, 8.3.4, 8.5
    • SCRs: WMLS-S-031 (M), WMLS-C-079 (M), WMLS-C-080 (M), WMLS-C-087 (M)
  • AC:
    • Evidence: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • External call to non-extern function is rejected.
    • URL fragment resolution selects target function deterministically.
    • External call path enforces access control before execution.

RQ-WMLS-002: Pragma handling and unit metadata

  • Requirement:
    • Support use url, use access, and use meta pragma semantics per grammar and processing rules.
  • Spec references:
    • WAP-193_101 6.7.1, 6.7.2, 6.7.3
    • SCRs: WMLS-S-043 (M), WMLS-S-044 (M), WMLS-S-045 (M), WMLS-C-087 (M)
  • AC:
    • Evidence: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • use url name mapping works for external calls.
    • More than one access pragma is rejected as error.
    • Access domain/path matching follows suffix/prefix element rules.

RQ-WMLS-003: URL handling for script invocation

  • Requirement:
    • Implement WAE URL schemes, fragment anchor handling, relative URL resolution against current compilation unit base.
  • Spec references:
    • WAP-193_101 8.3.1, 8.3.2, 8.3.6
    • SCRs: WMLS-C-078 (M), WMLS-C-079 (M), WMLS-C-082 (M)
  • AC:
    • Evidence: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • Relative URL unit references resolve to expected absolute URL.
    • Invalid URL references fail with deterministic non-fatal error mapping.

RQ-WMLS-004: Function call and return semantics

  • Requirement:
    • Exact arity matching, pass-by-value arguments, automatic empty-string return when function ends without explicit return.
  • Spec references:
    • WAP-193_101 6.4.1, 6.4.2.1, 6.4.3, 8.4.1, 8.4.3
    • SCRs: WMLS-S-030..033 (M), WMLS-C-083..086 (M)
  • AC:
    • Evidence: [x] wavescript::wap_runtime::tests::executes_local_calls_argument_order_locals_and_returns, registered_wap_unit_executes_wmls_502_operator_conversion_fixture, and wap-193-operator-conversions.wmlsc.hex; command: cargo test --manifest-path engine-wasm/engine/Cargo.toml wap_runtime.
    • Wrong-arity external calls fail deterministically before execution.
    • Implicit return value is "" with no undefined behavior.
    • Arguments appear in callee locals in declared order.

RQ-WMLS-005: Variable indexing and initialization

  • Requirement:
    • Allocate argument/local indexes exactly per spec and initialize locals to empty string when not explicitly initialized.
  • Spec references:
    • WAP-193_101 8.4.2, 8.4.4
    • SCRs: WMLS-S-047 (M), WMLS-S-049 (M), WMLS-C-084 (M), WMLS-C-086 (M)
  • AC:
    • Evidence: [x] wavescript::wap_runtime::tests::executes_local_calls_argument_order_locals_and_returns and the native/WASM wap-193-operator-conversions.wmlsc.hex parity tests.
    • Index assignment for args/locals matches section 8.4.2 rules.
    • Uninitialized locals read as empty string.

RQ-WMLS-006: Type system and conversion rules

  • Requirement:
    • Enforce Boolean, Integer, Float, String, Invalid semantics and automatic conversion rules.
  • Spec references:
    • WAP-193_101 6.8, 6.9, 6.10
    • SCRs: WMLS-C-072 (M), WMLS-C-073 (M), WMLS-C-075 (M), WMLS-C-076 (M), WMLS-C-077 (M), WMLS-C-071 (O), WMLS-C-074 (O)
  • AC:
    • Evidence: [x] value::tests::wmlscript_conversions_follow_the_effective_numeric_grammar, value::tests::wmlscript_string_conversion_is_deterministic_and_invalid_safe, and the source-section-derived opcode matrices in wavescript::wap_runtime::tests.
    • Conversion behavior matches per-type legal conversions for the selected floating-capable interpreter profile.
    • Invalid-conversion cases return invalid consistently.
    • Floating-point optionality is configurable and testable.
    • Scope note: integer-only optional behavior remains in RQ-WMLS-007; it is not part of the bounded Class C WMLS-502 closure.

RQ-WMLS-007: Integer-only mode behavior

  • Requirement:
    • Support integer-only behavior profile when float operations are unsupported.
  • Spec references:
    • WAP-193_101 13
    • WAP-194 6.4
    • SCRs: WMLS-C-112 (O), WMLSSL-017 (O)
  • AC:
    • Evidence: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • Float-related conversions/operations follow integer-only rules.
    • Float library calls return invalid in integer-only mode.
    • Lang.float() and Lang.parseFloat() behavior matches spec for integer-only mode.

RQ-WMLS-008: Bytecode binary format support

  • Requirement:
    • Decode and validate header, constant pool, pragma pool, function pool, and instruction stream structures.
  • Spec references:
    • WAP-193_101 9.2..9.6, 10
    • SCRs: WMLS-C-088..094 (M), WMLS-C-095..106 (M)
  • AC:
    • Evidence: [x] Add source-derived WAP-193 .wmlsc fixtures and direct tests for the header, constant pool, pragma pool, function pool, and effective instruction encoding.
    • The byte-exact wap-193-minimal-return-es.wmlsc.hex, wap-193-named-functions.wmlsc.hex, and wap-193-invalid-function-ref.wmlsc.hex fixtures decode to stable internal representations in native Rust and WASM.
    • Unsupported/reserved WAP types and opcodes fail structural verification.
    • WAP function and instruction boundaries are validated.
    • Registered units resolve external names from the decoded function table and execute the bounded WAP RETURN_ES subset with native/WASM and executable-story parity.
    • Scope note: this direct evidence keeps WMLS-C-088..108 partial and makes WMLS-C-069, WMLS-C-079, WMLS-C-094, and WMLS-C-105 executable-evidence candidates. It does not close either return opcode as a family, other opcode semantics, operators, conversions, or libraries.

RQ-WMLS-009: Bytecode verification gates

  • Requirement:
    • Perform integrity checks and runtime validity checks per chapter 11.
  • Spec references:
    • WAP-193_101 11.1, 11.2
    • SCRs: WMLS-C-107 (M), WMLS-C-108 (M)
  • AC:
    • Evidence: [x] Link direct WAP-193 structural integrity/runtime-validity fixtures.
    • Version/size/pool-count checks enforced by the strict decoder.
    • WAP jump targets are verified to instruction boundaries within function bounds.
    • Invalid WAP local/constant/function references fail deterministically before any selected function executes, including invalid references in an unselected function.
    • Standard-library and function indexes are validated against the WAP-194 Appendix A domains and source arities.
    • Reachable whole-function stack dataflow rejects underflow, the bounded 64-value overflow boundary, and inconsistent branch merges while accepting balanced loops, unreachable stack-invalid regions, and implicit/explicit returns.
    • Scope note: these checks verify bytecode before execution. WMLS-502 now consumes that verified representation for bounded language execution; WMLS-504 standard-library behavior remains open.

RQ-WMLS-010: Error detection and handling model

  • Requirement:
    • Runtime must distinguish and handle fatal/non-fatal errors per chapter 12 without process crash.
  • Spec references:
    • WAP-193_101 12
    • SCRs: WMLS-C-109 (M), WMLS-C-110 (M), WMLS-C-111 (M)
  • AC:
    • Evidence: [x] registered_wap_dataflow_failures_preserve_error_trace_taxonomy_and_recovery and wasm_wmls_501_library_and_dataflow_verification_matches_native prove deterministic integrity/resource classification, SCRIPT_TRAP serialization, and recovery after stack verification failures. pnpm test:story WMLS-501 replays the stable host-visible failure and replacement-invocation recovery path; full chapter 12 remains open.
    • WMLS-502 computational and conversion failures return the defined invalid value without aborting the invocation; floating underflow returns floating zero.
    • Fatal errors terminate current script invocation safely.
    • Host remains alive and recoverable after script failure.
    • Note (2026-07-25): corrected a spec-accuracy gap in the TypeError/StackUnderflow classification. WAP-193_101 12.3.1.7 lists Stack Underflow under Bytecode Errors (“[o]nly generated if compiler generates bad code”) and marks it Fatal, not Non-fatal; the VM’s TypeError is the same “compiler generated bad code” condition for a verified unit. Both now classify as fatal/integrity. This is a behavior change: scripts hitting either trap now abort invocation (invocation_aborted: true) instead of yielding invalid and continuing. See engine-wasm/engine/src/engine_script_types.rs classify_vm_trap / classify_vm_trap_category.
    • Gap: the full WMLS-505 chapter 12 matrix remains open, including integer-only floating-constant references. ScriptExecutionOutcome::non_fatal remains pinned for boundary errors that require a classified outcome; source-defined WMLScript computation/conversion failures complete normally with an invalid result instead.
    • Current implementation-class matrix:
      • Non-fatal: WMLS-502 divide/remainder by zero, numeric overflow, conversion range failure, illegal conversion, and invalid operands -> invalid; floating underflow -> floating zero.
      • Fatal: all current traps (TypeError, StackUnderflow, decode/integrity/resource/host-binding failures such as UnsupportedOpcode, TruncatedImmediate, Invalid*Index/Target, CallDepthExceeded, ExecutionLimitExceeded, HostCall*, etc.) -> invocation abort.
    • Current implementation-category matrix:
      • integrity: TypeError, StackUnderflow, and malformed decode/control-flow/local index/UTF-8/return-frame invariants
      • resource: stack/call-depth/step-limit exhaustion
      • host-binding: unavailable/failed host call bindings

RQ-WMLS-011: Content-type handling

  • Requirement:
    • Recognize textual and compiled WMLScript content types.
  • Spec references:
    • WAP-193_101 14
  • AC:
    • Evidence: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • text/vnd.wap.wmlscript and application/vnd.wap.wmlscriptc are routed to correct path.

RQ-WMLS-012: Standard library compliance baseline

  • Requirement:
    • Implement standard library behavior and error conventions from WMLSL.
  • Spec references:
    • WAP-194 6.1, 6.2, 6.3
    • SCRs: WMLSSL-014 (M), WMLSSL-015 (M), WMLSSL-016 (M)
  • AC:
    • Evidence: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • Invalid args return invalid with no side effects unless explicitly documented otherwise.
    • Argument coercions follow WMLScript conversion rules.

RQ-WMLS-013: Lang library coverage

  • Requirement:
    • Support Lang library function set and IDs.
  • Spec references:
    • WAP-194 section 7, Appendix A/B
    • SCRs: WMLSSL-018 (M), WMLSSL-031..045 (M)
  • AC:
    • Evidence: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • Unit tests cover each Lang function behavior and edge cases.

RQ-WMLS-014: Float library coverage

  • Requirement:
    • Support Float library function set where float mode is enabled.
  • Spec references:
    • WAP-194 section 8, Appendix A/B
    • SCRs: WMLSSL-019 (M), WMLSSL-046..054 (M), WMLSSL-017 (O)
  • AC:
    • Evidence: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • Unit tests cover each Float function in float-capable mode.
    • Integer-only mode returns invalid per section 6.4.

RQ-WMLS-015: String library coverage

  • Requirement:
    • Support String library function set and IDs.
  • Spec references:
    • WAP-194 section 9, Appendix A/B
    • SCRs: WMLSSL-020 (M), WMLSSL-055..070 (M)
  • AC:
    • Evidence: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • Unit tests cover each String function including bounds and invalid inputs.

RQ-WMLS-016: URL library coverage

  • Requirement:
    • Support URL library function set and IDs.
  • Spec references:
    • WAP-194 section 10, Appendix A/B
    • SCRs: WMLSSL-021 (M), WMLSSL-071..084 (M)
  • AC:
    • Evidence: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • Unit tests cover parse, resolve, escape/unescape, and load-string behavior.

RQ-WMLS-017: WMLBrowser context contract

  • Requirement:
    • WMLBrowser functions operate only with valid WML browser context; otherwise return invalid.
    • WMLBrowser accessors/mutators without required context must not mutate runtime state.
  • Spec references:
    • WAP-194 chapter 11 preface and 11.1..11.7
    • SCRs: WMLSSL-022 (M), WMLSSL-085..091 (M)
  • AC:
    • Evidence: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • Hostless/no-context invocation returns invalid.
    • getVar/setVar validation follows WML naming/value constraints.

RQ-WMLS-018: Deferred navigation semantics (go/prev)

  • Requirement:
    • go/prev requests are deferred until control returns to browser.
    • Multiple calls override each other; last call wins.
    • go("") cancels pending go/prev requests.
    • Fatal abort cancels pending navigation request.
  • Spec references:
    • WAP-194 11.3, 11.4
    • SCRs: WMLSSL-087 (M), WMLSSL-088 (M)
  • AC:
    • Evidence: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • In single invocation, go/go, go/prev, prev/go, prev/prev produce last-call behavior.
    • go("") yields no navigation.
    • Lang.abort() clears pending navigation intent.

RQ-WMLS-019: newContext and history/vars reset semantics

  • Requirement:
    • newContext clears WML vars and navigation history except current card.
    • newContext does not override a go request; prev request has no effect.
  • Spec references:
    • WAP-194 11.5
    • SCRs: WMLSSL-089 (M)
  • AC:
    • Evidence: [x] engine-wasm/engine/src/engine_tests.rs (wmlbrowser_new_context_clears_vars_and_history_and_prev_has_no_effect), engine-wasm/engine/src/wavescript/stdlib/wmlbrowser_tests.rs (new_context_requests_context_reset_when_context_is_valid, new_context_returns_invalid_without_active_card_context), and host/browser fixture engine-wasm/examples/source/wmlbrowser-context-fidelity.wml; command: cd engine-wasm/engine && cargo test wmlbrowser_new_context_clears_vars_and_history_and_prev_has_no_effect && cargo test new_context_requests_context_reset_when_context_is_valid && cargo test new_context_returns_invalid_without_active_card_context
    • Post-newContext, previous vars/history are cleared per spec.
    • Interaction with pending go/prev follows section 11.5 semantics.

RQ-WMLS-020: getCurrentCard semantics

  • Requirement:
    • Return smallest relative URL when same base applies, otherwise absolute URL.
    • Return invalid when no current card exists.
  • Spec references:
    • WAP-194 11.6
    • SCRs: WMLSSL-090 (M)
  • AC:
    • Evidence: [x] engine-wasm/engine/src/engine_tests.rs (wmlbrowser_get_current_card_returns_fragment_when_context_exists, wmlbrowser_get_current_card_returns_invalid_without_context) plus engine-wasm/engine/src/wavescript/stdlib/wmlbrowser_tests.rs (get_current_card_returns_fragment_for_current_context, get_current_card_returns_invalid_without_context) and fixture engine-wasm/examples/source/wmlbrowser-context-fidelity.wml; command: cd engine-wasm/engine && cargo test wmlbrowser_get_current_card_returns_fragment_when_context_exists && cargo test wmlbrowser_get_current_card_returns_invalid_without_context && cargo test get_current_card_returns_fragment_for_current_context && cargo test get_current_card_returns_invalid_without_context
    • Relative/absolute return mode covered by fixtures.
    • No-current-card case returns invalid.

RQ-WMLS-021: refresh semantics and immediate-refresh optionality

  • Requirement:
    • If immediate refresh is supported, execute refresh steps without restarting suspended timer and block until completion.
    • If immediate refresh unsupported, return invalid; browser still refreshes when control returns to UA.
  • Spec references:
    • WAP-194 11.7
    • WAP-194_103 section 3.3 (WMLBrowser.refresh immediate refresh support SCR, status O)
    • SCRs: WMLSSL-091 (M) and WMLSSL-C-095 (O, SIN clarification)
  • AC:
    • Evidence: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • Immediate-refresh-supported mode returns "" or non-empty failure string and updates current card.
    • Immediate-refresh-unsupported mode returns invalid and deferred card refresh still occurs on return.
    • Suspended timer is not restarted by refresh.

RQ-WMLS-022: Dialogs library contract

  • Requirement:
    • Support prompt, confirm, alert behavior and IDs.
  • Spec references:
    • WAP-194 chapter 12
    • SCRs: WMLSSL-023 (M), WMLSSL-092..094 (M)
  • AC:
    • Evidence: [ ] Strict closure still requires source-derived identifier, conversion, and interactive-result fixtures for WMLSSL-023 and WMLSSL-092..094.
    • Baseline evidence: [x] engine-wasm/engine/src/engine_tests/actions_timers.rs (timer_expiry_invokes_script_and_publishes_dialog_in_order) and engine-wasm/examples/source/timer-script-dialog.wml with adjacent timer-script-dialog.flow.json; command: pnpm test:story W0-05.
    • Dialog calls are exposed through the host boundary with the current deterministic placeholder return mapping.
    • UI interaction paths covered by integration tests in host harness.
    • Note: W0-05 closes the timer-to-script-to-dialog capability baseline, not strict Dialogs IDs, interactive result round-trips, or full WMLS-5.

SCR tracking summary for Waves milestones

These groups should be tracked explicitly in tickets and tests:

  1. WaveScript VM mandatory SCRs:
  • WMLS-C-069, WMLS-C-070, WMLS-C-072, WMLS-C-073, and WMLS-C-075..111 (41 M rows)
  1. WMLScript optional SCRs to gate by feature flags:
  • WMLS-C-071, WMLS-C-074, WMLS-C-112
  1. WMLScript libraries mandatory SCRs:
  • WMLSSL-014..016, WMLSSL-018..047, source-exact WMLSSL048 (normalized alias WMLSSL-048), and WMLSSL-049..094 (80 M rows)
  1. WMLScript libraries optional SCRs:
  • WMLSSL-017 (O)
  • WMLSSL-C-095 (O) from WAP-194_103

Implementation tracking rule

For each implementation ticket in docs/waves/WORK_ITEMS.md, include:

  • Spec: list of section refs and SCR IDs touched
  • AC: checklist copied or derived from the relevant RQ-WMLS-* entries above
  • Tests: explicit fixture/test IDs mapped to the same spec refs

Validate exact coverage with:

node scripts/check-wap-wmlscript-conformance-ledger.mjs