vyre-std 0.1.0

Vyre standard library: GPU DFA assembly pipeline, Aho-Corasick construction, and compositional arithmetic helpers
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

# vyre-std — the vyre standard library

**Status:** shipping, workspace member, published alongside `vyre` and
`vyre-conform`.
**Layer:** L2 — compositional helpers built from `vyre` core primitives.
**Scope:** GPU-native pattern matching (DFA assembly pipeline) and
arithmetic helpers.

---

## What ships today

### Pattern compilation — full GPU DFA assembly pipeline

```text
regex_to_nfa → Nfa → nfa_to_dfa → Dfa → dfa_minimize → Dfa → dfa_pack → PackedDfa
```

One-line API — patterns in, GPU-ready bytes out:

```rust
use vyre_std::pattern::{dfa_assemble, AssembleOptions, Pattern};

let packed = dfa_assemble(
    &[
        Pattern::Literal(b"GET /api"),
        Pattern::Literal(b"POST /api"),
        Pattern::Regex("PUT /api/v[0-9]+"),
    ],
    AssembleOptions::default(),
)?;
// `packed.bytes` is ready for a backend-specific dispatcher to upload.
```

Individual stages are also exposed for callers who need finer control:

- [`pattern::regex_to_nfa`] — Thompson construction. Supports literal,
  concat, `|`, `*`, `+`, `?`, `[abc]` (with ranges and negation), escape.
- [`pattern::nfa_to_dfa`] — subset construction with dead-state pruning.
- [`pattern::dfa_minimize`] — Hopcroft's partition refinement. Idempotent.
- [`pattern::dfa_pack`] — transition-table compression. Two formats:
  - `Dense` — fastest scan, 256 × 4 bytes per state.
  - `EquivClass` — byte-equivalence compression for narrow alphabets.
- [`pattern::dfa_assemble`] — composite entry: patterns → `PackedDfa`.
- [`pattern::cache`] — content-addressed compilation cache so the second
  compile of a pattern set is a file read.

### Arithmetic helpers — ~80 compositional Cat A ops

Every helper is a pure composition of core primitives; the conform gate
proves byte-identical agreement with the CPU reference:

- `saturating_{add,sub,mul}_{u8,u16,u32,u64,i8,i16,i32,i64}` — 24 ops.
- `wrapping_{add,sub,mul}_{u8,u16,u32,u64,i8,i16,i32,i64}` — 24 ops.
- `min_*`, `max_*`, `clamp_*`, `midpoint_*`, `abs_diff_*` — unsigned
  variants, 16+ ops.
- `div_ceil_*`, `div_floor_*`, `div_round_*` — unsigned variants, 6 ops.
- `lerp_f32`, `lerp_f64` — linear interpolation.

### Aho-Corasick DFA build

Literal-pattern-set construction (trie + failure links + output chain)
lives at `pattern::aho_corasick_build`. The CPU reference and WGSL kernel
agree byte-for-byte; the conform gate maintains five GOLDEN samples and
twenty KAT vectors as regression anchors.

---

## Compositional discipline

Every `std::` op is Category A. That means:

- It lowers to the same IR nodes a hand-optimizer would write.
- It introduces no new hardware intrinsic — those live in `vyre` core.
- The conform gate verifies the lowered output is byte-identical to the
  hand-written composition on every witness.

Ops that require a hardware intrinsic belong in core (`vyre`), not here.

## Design gates for new `std::` ops

A PR adding a new `std::` op must:

1. Reference a coordination note or issue describing the composition.
2. Declare `category = "A"` and a non-empty `composition_of` list
   naming the core primitives it builds from.
3. Pass conform-certify at L1 minimum.
4. Add a KAT vector set and an adversarial witness set.

## Related

- [`vyre`] — the core IR, primitives, and lowering contract.
- [`vyre-conform`] — the immune system that verifies this crate.
- [`vyre-spec`] — frozen data contracts shared across all three crates.
- [`LEGENDARY_PLAN.md`] — the build-out roadmap this crate follows.