rustcdc 0.4.0

Embeddable Rust CDC library focused on correctness-first capture primitives
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

# WASM Transform Conformance Contract

This document is the normative conformance profile for third-party WASM transform modules used with rustcdc.

## Conformance Requirements

A module is conformant only if it satisfies all requirements in this document.

## Export Requirements

### Required exports

- `memory`
- `alloc(i32) -> i32`
- `dealloc(i32, i32)`
- `transform(i32, i32) -> i64`
- `rustcdc_abi_version() -> i32` — must return `2`

### Optional exports

- `init(i32, i32) -> i32`
- `shutdown() -> i32`

Missing required exports or a wrong `rustcdc_abi_version` return value are hard conformance failures.

## Return Code Requirements

`transform` return value is a packed `i64`:

| Value | Meaning |
|---|---|
| `0` | Event dropped (filter-out) |
| `(out_ptr << 32) \| out_len` | Transformed event; `out_ptr > 0`, `out_len > 0` |

Returning a non-zero packed value with `out_ptr == 0` or `out_len <= 0` is a conformance failure.

`init` and `shutdown` return codes:

- `0`: success
- non-zero: lifecycle failure

## Memory Ownership Requirements

- `alloc` must never return 0 (address 0 is reserved).
- The guest must own and manage memory for the output region until the host has read it.
- The host calls `dealloc(input_ptr, input_len)` after `transform` returns.
- The host calls `dealloc(out_ptr, out_len)` after reading the output (if packed ≠ 0).

## Import Requirements

Allowed imports are limited to:

- `env.log`
- `env.get_metric`
- `env.record_metric`

Any additional import is a conformance failure.

## Data Contract Requirements

- Input payload must be canonical `Event` JSON.
- Successful output payload must be canonical `Event` JSON.
- Output pointer and length must address a valid, readable region of linear memory.

Malformed output payloads are conformance failures.

## Runtime Constraint Requirements

The module must execute correctly under runtime constraints:

- Memory cap configured by host (`WasmConfig.memory_limit_mb`, default 16 MiB).
- Timeout budget configured by host (`WasmConfig.timeout_ms`, default 50 ms).
- Sandboxed execution without direct file or network access.

Timeout and trap handling must not produce undefined behavior.

## Verification Procedure

Run conformance tests:

```bash
cargo test --all-features --test wasm_conformance_contract
cargo test --all-features wasm::runtime::tests --lib
```

Reference artifacts:

- `../fixtures/wasm/pass_through.wat`
- `../fixtures/wasm/filter_out_all.wat`
- `../tests/wasm_conformance_contract.rs`

## Pass Criteria

A module is conformant when:

1. All required exports are present and correctly typed.
2. `rustcdc_abi_version()` returns `2`.
3. No forbidden imports are present.
4. Memory ownership and `dealloc` contracts are satisfied.
5. Lifecycle and transform return contracts are satisfied.
6. Output payload deserialises into canonical `Event` JSON.
7. Conformance tests pass in the target embedding project.

## Related Documentation

- [wasm_transform_sdk.md](wasm_transform_sdk.md)
- [api.md](api.md)