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]>
501 lines
13 KiB
C
501 lines
13 KiB
C
/*
|
||
* WAI — Web AI media transport + execution.
|
||
*
|
||
* Auto-generated by cbindgen from src/ffi.rs. DO NOT EDIT — regenerate
|
||
* by rebuilding `wai-rs` (the build.rs runs cbindgen) or by running
|
||
* cbindgen --config cbindgen.toml --crate wai --output include/wai.h
|
||
*
|
||
* SDK contract:
|
||
* - Every `wai_*` function returns a `wai_status_t` (typedef int).
|
||
* 0 = ok; non-zero = see WAI_ERR_* below + wai_last_error().
|
||
* - Any `WaiBuffer` written into an out parameter MUST be freed via
|
||
* `wai_buffer_free`. Passing a zero-cap buffer to free is safe.
|
||
* - `wai_last_error()` returns a NUL-terminated UTF-8 string that is
|
||
* valid until the next wai_* call on the same thread.
|
||
*
|
||
* Build the library:
|
||
* cargo build --release # produces libwai.{so,dylib,a}
|
||
* Link with:
|
||
* gcc your.c -lwai # static or dynamic per linker
|
||
*/
|
||
|
||
|
||
#ifndef WAI_H
|
||
#define WAI_H
|
||
|
||
#pragma once
|
||
|
||
#include <stdarg.h>
|
||
#include <stdbool.h>
|
||
#include <stdint.h>
|
||
#include <stdlib.h>
|
||
|
||
#define WAI_OK 0
|
||
|
||
#define WAI_ERR_INVALID_ARG 1
|
||
|
||
#define WAI_ERR_CODEC 2
|
||
|
||
#define WAI_ERR_CONTAINER 3
|
||
|
||
#define WAI_ERR_PANIC 4
|
||
|
||
#define MARKER_SOC 65408
|
||
|
||
#define MARKER_EOC 65409
|
||
|
||
#define MARKER_PIH 65410
|
||
|
||
#define MARKER_TON 65411
|
||
|
||
#define MARKER_RDI 65412
|
||
|
||
#define MARKER_SOZ 65416
|
||
|
||
#define MARKER_SORP 65417
|
||
|
||
#define MARKER_SORS 65418
|
||
|
||
#define MARKER_SOQ 65419
|
||
|
||
#define MARKER_UDI 65420
|
||
|
||
#define SECTION_CONTRACT 1
|
||
|
||
#define SECTION_GRAPH 2
|
||
|
||
#define SECTION_ASSETS 3
|
||
|
||
#define SECTION_OPLOG 4
|
||
|
||
#define SECTION_SEAL 5
|
||
|
||
/**
|
||
* Payload = a record body (`n_cells u16 | cells…`). Target MUST
|
||
* equal `mint_node_id(actor, lamport)`. Resolution: LWW.
|
||
*/
|
||
#define CREATE 1
|
||
|
||
/**
|
||
* `pos[3] | vel[3] | scalar` (7 × i64). Target MUST equal
|
||
* `mint_node_id(actor, lamport)`. Resolution: LWW.
|
||
*/
|
||
#define CREATE 1
|
||
|
||
/**
|
||
* `pos[3] | vel[3] | radius | restitution` (8 × i64). Target MUST
|
||
* equal `mint_node_id(actor, lamport)`. Resolution: LWW.
|
||
*/
|
||
#define CREATE 1
|
||
|
||
/**
|
||
* `parent[16] | translation[3] | rotation[4] | scale[3]`
|
||
* (16 + 10×`i64` Fx = 96 bytes). Target MUST equal
|
||
* `mint_node_id(actor, lamport)`. `parent` is another bone's node
|
||
* id, or all-zero for a root.
|
||
*/
|
||
#define CREATE 1
|
||
|
||
/**
|
||
* Empty payload. Resolution: LWW.
|
||
*/
|
||
#define DELETE 2
|
||
|
||
/**
|
||
* Empty payload. Resolution: LWW.
|
||
*/
|
||
#define DELETE 2
|
||
|
||
/**
|
||
* Empty payload. Resolution: LWW.
|
||
*/
|
||
#define DELETE 2
|
||
|
||
/**
|
||
* Empty payload — remove the bone.
|
||
*/
|
||
#define DELETE 2
|
||
|
||
/**
|
||
* Empty payload; removes a particle or member. LWW.
|
||
*/
|
||
#define DELETE 2
|
||
|
||
/**
|
||
* `field_idx u16 | cell(tag u8 | value)` — replace one cell.
|
||
* Resolution: LWW.
|
||
*/
|
||
#define SET_CELL 16
|
||
|
||
/**
|
||
* `field_idx u16 | i64` — add to an `Int` cell (saturating).
|
||
* Resolution: SUM.
|
||
*/
|
||
#define ADD_INT 17
|
||
|
||
/**
|
||
* `field_idx u16 | i64` (Fx bits) — add to a `Fixed` cell
|
||
* (saturating). Resolution: SUM.
|
||
*/
|
||
#define ADD_FIXED 18
|
||
|
||
#define Fx_FRAC_BITS 32
|
||
|
||
/**
|
||
* `scalar` (1 × i64). Resolution: LWW.
|
||
*/
|
||
#define SET_SCALAR 3
|
||
|
||
/**
|
||
* `dv[3]` (3 × i64) added to velocity. Resolution: SUM — two
|
||
* actors shoving the same node both act; neither is discarded.
|
||
*/
|
||
#define IMPULSE 4
|
||
|
||
/**
|
||
* `dv[3]` (3 × i64) added to velocity. Resolution: SUM.
|
||
*/
|
||
#define IMPULSE 4
|
||
|
||
/**
|
||
* `dv[3]` (3 × i64) added to a particle's velocity. SUM.
|
||
*/
|
||
#define IMPULSE 4
|
||
|
||
/**
|
||
* `pos[3]` (3 × i64). Resolution: LWW.
|
||
*/
|
||
#define SET_POS 5
|
||
|
||
/**
|
||
* `pos[3]` (3 × i64). Resolution: LWW.
|
||
*/
|
||
#define SET_POS 5
|
||
|
||
/**
|
||
* `pos[3]` (3 × i64) on a particle. LWW.
|
||
*/
|
||
#define SET_POS 5
|
||
|
||
/**
|
||
* `rotation[4]` (4×`i64` Fx quaternion x,y,z,w) — the animation
|
||
* driver: set a joint's local rotation.
|
||
*/
|
||
#define SET_ROTATION 16
|
||
|
||
/**
|
||
* `translation[3]` (3×`i64` Fx).
|
||
*/
|
||
#define SET_TRANSLATION 17
|
||
|
||
/**
|
||
* `scale[3]` (3×`i64` Fx).
|
||
*/
|
||
#define SET_SCALE 18
|
||
|
||
/**
|
||
* Create a particle: `pos[3] | vel[3] | inv_mass` (7 × i64).
|
||
* `inv_mass == 0` is an anchor (infinite mass — foundations).
|
||
* Target MUST equal `mint_node_id(actor, lamport)`. LWW.
|
||
*/
|
||
#define CREATE_PARTICLE 1
|
||
|
||
/**
|
||
* Create a member between two particles:
|
||
* `node_a (16 B) | node_b (16 B) | yield_strain (i64)`.
|
||
* Rest length is measured from the endpoints' current positions
|
||
* at apply time (weld what's there — deterministic, since apply
|
||
* order is canonical). Target MUST be minted; endpoints missing
|
||
* or coincident → deterministic no-op. LWW.
|
||
*/
|
||
#define CREATE_MEMBER 16
|
||
|
||
/**
|
||
* Q32.32 fixed-point value.
|
||
*/
|
||
typedef struct Fx Fx;
|
||
|
||
typedef struct wai_buffer_t {
|
||
uint8_t *data;
|
||
uintptr_t len;
|
||
uintptr_t cap;
|
||
} wai_buffer_t;
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif // __cplusplus
|
||
|
||
/**
|
||
* Free a buffer previously returned by any `wai_*_encode` /
|
||
* `wai_*_decode` / `wai_envelope_*` call. Safe to call with a null
|
||
* or zero-cap buffer.
|
||
*
|
||
* # Safety
|
||
* `buf.data` must have been produced by this crate.
|
||
*/
|
||
void wai_buffer_free(struct wai_buffer_t buf);
|
||
|
||
/**
|
||
* Returns a pointer to the most recent error message for this thread,
|
||
* or null if there is none. The pointer is valid until the next FFI
|
||
* call on this thread that sets an error.
|
||
*/
|
||
const char *wai_last_error(void);
|
||
|
||
/**
|
||
* Encode RGB pixels (row-major, 3 bytes per pixel) as PNG.
|
||
*
|
||
* # Safety
|
||
* `rgb` must point to a valid RGB buffer of at least `len` bytes;
|
||
* `out` must be a writable `WaiBuffer*`. Pass `(null, 0)` for empty.
|
||
*/
|
||
|
||
int wai_image_png_encode(const uint8_t *rgb,
|
||
uintptr_t len,
|
||
uint32_t h,
|
||
uint32_t w,
|
||
struct wai_buffer_t *out);
|
||
|
||
/**
|
||
* Decode a PNG byte stream to RGB. Returns `(rgb, h, w)`.
|
||
*/
|
||
|
||
int wai_image_png_decode(const uint8_t *bytes,
|
||
uintptr_t len,
|
||
struct wai_buffer_t *out,
|
||
uint32_t *out_h,
|
||
uint32_t *out_w);
|
||
|
||
|
||
int wai_image_avif_encode(const uint8_t *rgb,
|
||
uintptr_t len,
|
||
uint32_t h,
|
||
uint32_t w,
|
||
uint8_t quality,
|
||
struct wai_buffer_t *out);
|
||
|
||
|
||
int wai_image_avif_decode(const uint8_t *bytes,
|
||
uintptr_t len,
|
||
struct wai_buffer_t *out,
|
||
uint32_t *out_h,
|
||
uint32_t *out_w);
|
||
|
||
/**
|
||
* `quality = 0` ⇒ lossless. Otherwise butteraugli distance proxy
|
||
* (higher quality = smaller distance internally).
|
||
*/
|
||
|
||
int wai_image_jxl_encode(const uint8_t *rgb,
|
||
uintptr_t len,
|
||
uint32_t h,
|
||
uint32_t w,
|
||
uint8_t quality,
|
||
struct wai_buffer_t *out);
|
||
|
||
|
||
int wai_image_jxl_decode(const uint8_t *bytes,
|
||
uintptr_t len,
|
||
struct wai_buffer_t *out,
|
||
uint32_t *out_h,
|
||
uint32_t *out_w);
|
||
|
||
|
||
int wai_audio_opus_encode(const float *samples,
|
||
uintptr_t n,
|
||
uint32_t sr,
|
||
int32_t bitrate_bps,
|
||
struct wai_buffer_t *out);
|
||
|
||
|
||
int wai_audio_opus_decode(const uint8_t *bytes,
|
||
uintptr_t len,
|
||
struct wai_buffer_t *out,
|
||
uint32_t *out_sr);
|
||
|
||
|
||
int wai_audio_flac_encode(const float *samples,
|
||
uintptr_t n,
|
||
uint32_t sr,
|
||
struct wai_buffer_t *out);
|
||
|
||
|
||
int wai_audio_flac_decode(const uint8_t *bytes,
|
||
uintptr_t len,
|
||
struct wai_buffer_t *out,
|
||
uint32_t *out_sr);
|
||
|
||
|
||
int wai_text_zstd_encode(const uint8_t *data,
|
||
uintptr_t len,
|
||
int32_t level,
|
||
struct wai_buffer_t *out);
|
||
|
||
int wai_text_zstd_decode(const uint8_t *bytes, uintptr_t len, struct wai_buffer_t *out);
|
||
|
||
|
||
int wai_text_xz_encode(const uint8_t *data,
|
||
uintptr_t len,
|
||
uint32_t level,
|
||
struct wai_buffer_t *out);
|
||
|
||
int wai_text_xz_decode(const uint8_t *bytes, uintptr_t len, struct wai_buffer_t *out);
|
||
|
||
/**
|
||
* Encode a sequence of `n` RGB frames as AV1.
|
||
*/
|
||
|
||
int wai_video_av1_encode(const uint8_t *rgb,
|
||
uintptr_t len,
|
||
uint32_t n,
|
||
uint32_t h,
|
||
uint32_t w,
|
||
uint32_t fps_num,
|
||
uint32_t fps_den,
|
||
uint8_t lossless,
|
||
uint8_t quality,
|
||
struct wai_buffer_t *out);
|
||
|
||
/**
|
||
* Decode an AV1 WAI payload to a packed RGB buffer `n*h*w*3` bytes.
|
||
*/
|
||
|
||
int wai_video_av1_decode(const uint8_t *bytes,
|
||
uintptr_t len,
|
||
struct wai_buffer_t *out,
|
||
uint32_t *out_n,
|
||
uint32_t *out_h,
|
||
uint32_t *out_w,
|
||
uint32_t *out_fps_num,
|
||
uint32_t *out_fps_den);
|
||
|
||
/**
|
||
* Builds a complete WAI file from a codec-produced payload + manifest
|
||
* fields. `manifest_json` is a UTF-8 JSON object overriding/supplying
|
||
* any fields; `payload` is the bytes from one of the codec encoders.
|
||
*/
|
||
|
||
int wai_envelope_pack(const char *manifest_json,
|
||
const uint8_t *payload,
|
||
uintptr_t payload_len,
|
||
struct wai_buffer_t *out);
|
||
|
||
/**
|
||
* Detect WAI version from a byte stream. Returns 1 (WAI1), 2 (WAI2),
|
||
* or 0 with an error message in `wai_last_error` for unknown magic.
|
||
*/
|
||
int wai_envelope_detect_version(const uint8_t *bytes, uintptr_t len);
|
||
|
||
/**
|
||
* Pack a WAI2 multi-rendition envelope.
|
||
*
|
||
* - `manifest_json` must declare a `renditions` array of length `n`.
|
||
* - `payload_data` is an array of `n` byte-buffer pointers.
|
||
* - `payload_lens` is the matching array of `n` lengths.
|
||
* - The i-th payload pairs with `manifest.renditions[i]`.
|
||
*
|
||
* # Safety
|
||
* All array pointers must point to valid memory of the declared length.
|
||
*/
|
||
|
||
int wai_envelope_pack_multi(const char *manifest_json,
|
||
const uint8_t *const *payload_data,
|
||
const uintptr_t *payload_lens,
|
||
uintptr_t n_payloads,
|
||
struct wai_buffer_t *out);
|
||
|
||
/**
|
||
* Parse a WAI2 envelope. Writes three outputs:
|
||
*
|
||
* - `out_manifest` — the original manifest JSON (UTF-8 bytes, no NUL)
|
||
* - `out_renditions_json` — a JSON array of `{capability, kind, offset,
|
||
* length}` entries. `offset` is into `out_payload_block`, `length`
|
||
* is the rendition's payload byte count.
|
||
* - `out_payload_block` — every rendition's payload bytes, packed
|
||
* contiguously. The caller indexes via the JSON above.
|
||
*
|
||
* This avoids exposing a C struct array (and the ownership pain that
|
||
* comes with it). Any JSON parser the consumer already has decodes
|
||
* the rendition table in two lines.
|
||
*/
|
||
|
||
int wai_envelope_unpack_multi(const uint8_t *bytes,
|
||
uintptr_t len,
|
||
struct wai_buffer_t *out_manifest,
|
||
struct wai_buffer_t *out_renditions_json,
|
||
struct wai_buffer_t *out_payload_block);
|
||
|
||
/**
|
||
* Parses a WAI envelope. Writes the manifest as JSON to `out_manifest`
|
||
* and the raw payload to `out_payload`.
|
||
*/
|
||
|
||
int wai_envelope_unpack(const uint8_t *bytes,
|
||
uintptr_t len,
|
||
struct wai_buffer_t *out_manifest,
|
||
struct wai_buffer_t *out_payload);
|
||
|
||
/**
|
||
* Decode a `wai.neural.<audio>` envelope (encodec32 / dac / mimi /
|
||
* wavtokenizer). Writes mono `f32` samples into `out_samples`; the
|
||
* caller reads them as `float*` of length `out_samples.len / 4`.
|
||
*
|
||
* # Safety
|
||
* `envelope` valid for `envelope_len` bytes. `model_path` NUL-terminated
|
||
* UTF-8 path to the decoder.onnx. `out_samples` writable `WaiBuffer*`.
|
||
* `out_sample_rate` writable `uint32_t*` (or null to skip).
|
||
*/
|
||
|
||
int wai_neural_decode_audio(const uint8_t *envelope,
|
||
uintptr_t envelope_len,
|
||
const char *model_path,
|
||
struct wai_buffer_t *out_samples,
|
||
uint32_t *out_sample_rate);
|
||
|
||
/**
|
||
* Decode a `wai.neural.bmshj2018` envelope. Writes packed RGB
|
||
* (row-major, 3 bytes/pixel) into `out_rgb`; writes width/height
|
||
* into `*out_width` / `*out_height`.
|
||
*
|
||
* # Safety
|
||
* See `wai_neural_decode_audio`.
|
||
*/
|
||
|
||
int wai_neural_decode_image(const uint8_t *envelope,
|
||
uintptr_t envelope_len,
|
||
const char *model_path,
|
||
struct wai_buffer_t *out_rgb,
|
||
uint32_t *out_width,
|
||
uint32_t *out_height);
|
||
|
||
/**
|
||
* Decode a `wai.neural.video_bmshj2018` envelope. Writes all frames
|
||
* concatenated (frame 0 RGB, then frame 1 RGB, …) into
|
||
* `out_frames_concat`; the caller splits at `width*height*3` strides.
|
||
*
|
||
* # Safety
|
||
* See `wai_neural_decode_audio`.
|
||
*/
|
||
|
||
int wai_neural_decode_video(const uint8_t *envelope,
|
||
uintptr_t envelope_len,
|
||
const char *model_path,
|
||
struct wai_buffer_t *out_frames_concat,
|
||
uint32_t *out_n_frames,
|
||
uint32_t *out_width,
|
||
uint32_t *out_height,
|
||
uint32_t *out_fps_x_1000);
|
||
|
||
#ifdef __cplusplus
|
||
} // extern "C"
|
||
#endif // __cplusplus
|
||
|
||
#endif /* WAI_H */
|