WAI Extension: Haptics

Mirrored from the canonical text at commit 117bad22 (2026-10-01).

Status: Draft. Phase 2 of the cargo roadmap. Touch as instructions: ship a keyframed intensity/sharpness envelope, the sink reconstructs an actuator signal. Conformance is sample-equivalence. Reference impl: the haptic feature of wai-rs; corpus: haptic-conformance/; live sink: wai.transaction.science/haptics. Keywords MUST, MUST NOT, SHOULD, MAY are RFC 2119/8174.

1. Scope and model

A wai.haptic.signal object is a per-channel keyframed envelope of intensity and sharpness (the Core-Haptics-shaped pair every modern actuator API maps to) that the sink reconstructs to a per-sample buffer and plays on whatever actuators it has. It is lever 3 (instructions-at-the-sink) for touch — an effect is a few hundred bytes, not a recorded waveform.

In scope: the container, the deterministic reconstruct contract, the sample-equivalence conformance criterion, the fallback floor, the receipt profile.

Out of scope: a transport; actuator hardware specifics (the channel→actuator binding is the sink’s); carrier synthesis (the signal is an amplitude/sharpness envelope, not a modulated waveform — the deterministic floor stays trig-free).

Relationship to the core spec: mirrors interactive-worlds / spatial audio. The reconstruct runs in the wai.det.fixed64 floor; media takes the informational value "haptic"; wai.haptic.signal is authoritative.

2. Container (WHAP)

"WHAP" | u16 n_sections | section table (u8 kind, u32 off, u32 len) | sections

2.1 Contract

{ "sample_rate": 1000, "numeric": "wai.det.fixed64",
  "channels": 1, "duration": 1500 }

Haptic rates are low (≈1 kHz); duration is in samples.

2.2 Channel signals

n_channels u32, then per channel: n_keys u16, then n × ( pos_sample u64 | intensity i64 Fx | sharpness i64 Fx ). Both fields are in [0, 1]. Between keyframes they linear-interpolate in Fx; before the first / after the last key they hold.

3. Reconstruct contract

For each channel, for each sample t ∈ [0, duration): intensity(t), sharpness(t) = the Fx linear interpolation of the channel’s keyframes at t, each clamped to [0,1] and quantized to a u8 (round(v · 255), half away from zero, in integer space). The canonical reconstruction is, per channel, the interleaved [intensity, sharpness] u8 pairs.

4. Conformance — sample-equivalence

Given the same wai.haptic.signal, a conforming sink MUST reconstruct the identical canonical u8 buffer, hence the identical BLAKE3 — on every machine, no tolerance parameter.

signal_hash = BLAKE3("wai:haptic-signal\x01" || per-channel u8 pairs)

5. Fallback floor

A sink with no actuators ignores the signal (haptics are supplementary); there is no perceptual substitute to fall back to, so fallback is typically null. A sink MAY surface the envelope visually (a waveform) — presentation, not conformance.

6. Receipt (JWP profile)

signal_hash is the identity; the group’s objects are per-channel reconstruction blocks, Merkle-bound; one Ed25519 signature over signal_hash + root + work (= duration × channels) + carried joules_micro; parent_receipt_hash chains — the worlds/audio receipt shape reused. The figure’s acquisition class rides beside it as an optional signed label (energy-measurement §2.8): absent, the receipt keeps its legacy bytes and the figure is unlabelled; present, it is inside the signature. The reference meter labels every figure it measures OnChipCounter, with its declared uncertainty.

Appendix

Sample-equivalence is replay/mixdown-equivalence with the tick replaced by the haptic sample. The envelope is trig-free by construction (amplitude + sharpness, not a modulated carrier), so the Fx floor reconstructs it exactly with +,−,×,÷ alone — the simplest cargo class to make bit-exact, which is why it’s the fast Phase-2 win.