WAP LabsProject atlas

docs/waves/wmlscript_spec_traceability.md

Waves WMLScript Spec Traceability

Version: v0.4 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/*.
  • Existing implementation is a project-specific nine-opcode progression baseline, not a WAP-193 compilation-unit decoder.
  • 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, 23 partial / 18 missing / 0 implemented;
    • Libraries: 80 required, 14 partial / 66 missing / 0 implemented;
    • direct normative tests: 0.
  • 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: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • Wrong-arity calls fail deterministically.
    • 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: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • 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: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • Conversion behavior matches per-type legal conversions.
    • Invalid-conversion cases return invalid consistently.
    • Floating-point optionality is configurable and testable.

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: [ ] Add source-derived WAP-193 .wmlsc fixtures and direct tests for the header, constant pool, pragma pool, function pool, and effective instruction encoding.
    • Known-good WAP .wmlsc fixtures decode to stable internal representation.
    • Unsupported/reserved WAP types fail verification before execution.
    • WAP function and instruction boundaries are validated.
    • Provisional evidence only: current decoder tests reject malformed input in the project-specific nine-opcode format. They do not parse WAP-193 compilation units and therefore do not close WMLS-C-088..108.

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: [ ] Link direct WAP-193 integrity/runtime-validity fixtures; local decoder/VM bounds tests are provisional architecture evidence.
    • Version/size/pool-count checks enforced.
    • WAP jump targets are verified to instruction boundaries within function bounds.
    • Invalid WAP local/constant/library/function indexes trap deterministically.

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: [ ] Link concrete tests/fixtures, file paths, and commands proving this requirement.
    • Non-fatal errors return defined error/invalid results where applicable.
    • 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: no current VmTrap variant maps to non-fatal. The VM has no opcodes for the chapter 12.4 Non-fatal Computational/Constant-Reference/Conversion errors (divide-by-zero, integer/float overflow/underflow, NaN/infinite float constant, illegal float reference, integer/float conversion range) — those require new opcodes (e.g. integer divide), which is W1-04/opcode-expansion scope, not this ticket. The ScriptExecutionOutcome::non_fatal contract shape is still pinned directly by non_fatal_execution_outcome_contract_shape in engine-wasm/engine/src/engine_tests/script_runtime.rs so it stays correct once such an opcode lands.
    • Current implementation-class matrix:
      • Non-fatal: none currently reachable (see gap above).
      • 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