# Module Contract Guide

This guide documents the contract `qip` expects for modules, and how it passes input in and reads output back.

## Quick Model

- A `.wasm` module file can be tiny, while instances’ initial linear memory can be much larger.
- WebAssembly memory is broken into multiple pages, where each page is `64 KiB` each.
- `qip` writes input into module memory, calls `run`, then reads output from module memory.

## Run Mode Contract

In `qip run`, modules can export pointer/cap values as either:

- zero-arg functions returning `i32` (common with Zig & C), or
- `i32` globals (common with `.wat`)

`qip` accepts both styles.

Required input exports:

- `input_ptr`
- one of `input_utf8_cap` or `input_bytes_cap`

Optional output exports:

- `output_ptr`
- one of `output_utf8_cap`, `output_bytes_cap`, or `output_i32_cap`

Required function:

- `run(input_size) -> output_size`

If `output_ptr` + output cap are not exported, `qip` falls back to printing `Ran: <run_return_value>`.

### Optional Uniforms (`uniform_set_<key>`)

Modules may export uniform setter functions and callers can pass values via query args.

Uniform export contract:

- Name must be `uniform_set_<key>` where `<key>` matches the query key.
- Setter must accept exactly one parameter.
- Supported parameter types are: `i32`, `i64`, `f32`, `f64`.
- Setter return value is ignored by `qip` (you can still return the clamped/applied value).
- Exception: image modules may also export `uniform_set_width_and_height(f32, f32)`; this is host-managed and not set via query args.

Host behavior:

- Uniforms are applied after module instantiation and before `run(...)` (or before tile execution in image mode).
- If a query key is provided but the module does not export `uniform_set_<key>`, execution fails.
- If parsing fails for the expected numeric type, execution fails.
- Integer uniforms (`i32`, `i64`) parse decimal as signed values by default.
- For integer uniforms, hexadecimal is accepted only when prefixed with `0x` (or `0X`) and is parsed as an unsigned bit pattern.
- Uniform keys are applied in sorted key order; do not rely on setter call order for dependent state changes.

CLI syntax:

- Put uniform query args immediately after the module path.
- Quote the full query arg in shells so `&` is not treated as a command separator.
- `qip run ... module.wasm '?key=value'`
- `qip run ... module.wasm '?width=900&height=400&font_size=48'`
- `qip image ... module.wasm '?key=value&other=1.5'`
- Multiple query args may follow the same module path and are merged.

Examples:

```bash
# i32 uniform
qip run modules/utf8/text-to-bmp.wasm '?cols=120'

# f32 uniforms
qip image -i in.jpg -o out.png modules/rgba/color-halftone.wasm '?max_radius=2.0&angle_c=0.26'

# packed 32-bit RGBA passed as hexadecimal (0xRRGGBBAA)
qip run modules/image/svg+xml/svg-recolor-current-color.wasm '?color_rgba=0xff5511ff'
```

Zig example:

```zig
var color_rgba: u32 = 0x000000FF;

// For wasm i32 uniforms, qip maps 0x-prefixed values as raw 32-bit bits.
export fn uniform_set_color_rgba(v: u32) u32 {
    color_rgba = v;
    return color_rgba;
}
```

## WebAssembly Module Contract

### `input_utf8_cap` / `input_bytes_cap`

Use `input_utf8_cap` for UTF-8 text input and `input_bytes_cap` for binary input.

### `output_utf8_cap` / `output_bytes_cap` / `output_i32_cap`

Use `output_utf8_cap` for UTF-8 text output, `output_bytes_cap` for binary output, and `output_i32_cap` for `i32[]` output.

If output exports are omitted, the return value of `run` is used as the result.

If output exports are present, the return value of `run` is used as the output size.

### Optional Content Type Metadata

Run modules may optionally export content type metadata for friendlier composition and host `Content-Type` selection.

- `input_content_type_ptr` / `input_content_type_size`
- `output_content_type_ptr` / `output_content_type_size`

Rules:

- These exports are optional. Omit them when content type is unknown or intentionally generic.
- Export exactly one MIME type value when present.
- Do not use media ranges (for example, `text/*` or `*/*`).
- Do not use comma-separated MIME lists.
- Omit input content type for modules that accept any UTF-8 text regardless of media type (for example: plain text, HTML, XML).
- Omit output content type for generic raw bytes and `i32[]` outputs unless the module guarantees a specific media type.
- Do not export `text/plain` for generic UTF-8 modules; `input_utf8_cap` / `output_utf8_cap` already imply plain UTF-8 text.
- Export content type when the module knows it exactly (for example: `text/javascript`, `text/html`, `image/bmp`).
- Export only the media type value. Do not append `charset=utf-8`; UTF-8 is already implied by `input_utf8_cap` / `output_utf8_cap`.
- If the host/caller provides an initial content type, treat it as authoritative for composition.
- For direct user ingress in `qip run` (stdin or `-i` file bytes), there is currently no separate content-type channel; trust user intent for the first stage.

### Content Type Composition Semantics

These are the composition rules for run-module pipelines:

- The pipeline starts with an optional initial content type from the caller/host context.
- For direct user ingress in `qip run`, when initial content type is absent, the first module is allowed by user intent (stdin/`-i` is trusted as the expected type).
- If a module exports `input_content_type_ptr`/`input_content_type_size`, the incoming content type must exactly match that MIME type.
- If a module does not export input content type and uses `input_utf8_cap`, it is treated as a generic UTF-8 transform and may compose with any UTF-8 pipeline input.
- If a module does not export input content type and uses `input_bytes_cap`, it is treated as a generic bytes transform and may compose with any bytes pipeline input.
- If a module exports `output_content_type_ptr`/`output_content_type_size`, that MIME type becomes the pipeline content type for downstream stages.
- If a module does not export output content type and uses `output_utf8_cap`, the existing pipeline content type is preserved.
- If a module does not export output content type and uses `output_bytes_cap`, the existing pipeline content type is preserved.
- Generic UTF-8 utility modules (for example, uppercase/trim/rewrite helpers) should usually omit content type metadata so they can run on any UTF-8 text while preserving upstream content type.
- Generic bytes utility modules (for example, `base64-encode.wasm` style byte transforms) should usually omit content type metadata so they can run on any bytes while preserving upstream content type.
- Example: `curl ... | qip run modules/text/html/html-link-extractor.wasm` composes by trusting user-provided stdin for the first stage (`text/html` expected by the module).

## Input/Output Semantics

Input:

- `qip` ensures `len(input) <= input_*_cap`.
- Input bytes are written to memory at `input_ptr`.
- If input is larger than cap, execution fails with `Input is too large`.

Output:

- `run` return value is interpreted as element count.
- For UTF-8 or raw bytes output, element size is `1` byte.
- For `output_i32_cap`, element size is `4` bytes aka `32` bits.
- `qip` checks returned count does not exceed exported output cap.

Capacity units:

- `input_utf8_cap`, `input_bytes_cap`, `output_utf8_cap`, `output_bytes_cap`: bytes.
- `output_i32_cap`: number of `i32` items.

## Memory Layout Recommendations

- Keep input and output buffers disjoint.
- Validate `input_size` and trap on out-of-bounds assumptions drifting between host and module.
- Reserve explicit scratch space if needed.
- Preferred for data-preserving transforms: trap on invalid input/overflow so bad data does not silently become empty output.
- Prefer trapping over silent truncation when output buffers fill.
- Use `return 0` only when empty output is an intentional, non-error result.

## Image Mode Memory

For `qip image` / RGBA filters:

- Required: `input_ptr`, `input_bytes_cap`, `tile_rgba_f32_64x64`.
- Host writes tile data into memory at `input_ptr`.
- Filter runs in-place and host reads back from the same buffer.

Tile byte size:

`tile_bytes = tile_span * tile_span * 4 channels * 4 bytes(float32)`

Where:

- `tile_span = 64` without halo.
- `tile_span = 64 + 2 * halo` with halo.

If any stage exports `calculate_halo_px` with `halo > 0`, host uses the full-image float32 pipeline for all stages in the contiguous image block.

See also: `IMAGE.md`.

## Practical Checklist

- Verify your exported caps match actual writable memory.
- Test both normal and oversized input.
- Check module trap behavior for malformed/oversized input.