46c5688b86
Commit the WAI standard source: a content + capability-dispatch standard
whose thesis is "carries whatever it can reconstruct, verifies whatever
it carries." Source only — large vendored/model assets and build output
are gitignored.
Reconstruct classes (each: spec + conformance corpus + in-tab browser
sink that re-derives the corpus hash, one wai.det.fixed64 fixed-point
floor, one *-equivalence apiece):
- interactive worlds (replay-equivalence) + 3 sim registrants,
multiplayer over a relay, session receipts, glTF + real SPZ assets
- spatial audio (mixdown-equivalence)
- haptics (sample-equivalence)
- state-feeds (replay-equivalence, non-physics sim)
- avatars / digital humans (pose-equivalence) + telepresence over the relay
- volumetric / 4D splats (frame-state-equivalence) + WebGPU EWA render,
real-SPZ-derived clip
Verify half (lever 4):
- asset provenance: a signed, energy-accounted lineage for opaque
captured content WAI does not reconstruct; tamper-evident, in-tab.
Cross-cutting: JWP receipt profiles per class; a native energy meter
(IOReport via macmon, no sudo) emitting receipts with REAL measured
joules; the learned-image/neural codec family and JPEG AI entropy port
from earlier work.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
100 lines
3.7 KiB
Markdown
100 lines
3.7 KiB
Markdown
# WAI Extension: Haptics
|
||
|
||
> 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
|
||
```
|
||
|
||
| kind | section | required |
|
||
|---|---|---|
|
||
| `0x01` | contract (canonical JSON) | REQUIRED |
|
||
| `0x02` | channel signals | REQUIRED |
|
||
|
||
### 2.1 Contract
|
||
|
||
```json
|
||
{ "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.
|
||
|
||
## 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.
|